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SYSTEM AND METHODS FOR ACQUIRING IMAGES FROM IMAGING 

DEVICES 
Field of the Invention 

This invention is generally directed toward acquiring a graphic image with 
5 imaging devices such as scanners and digital cameras, and more specifically, to an 
application program interface (API) for communicating with image acquisition 
devices to acquire a graphic image. 

Background of the Invention 
In the early days of desktop publishing, most publications contained only text 
10 and simple black and white line drawings that were output to black and white laser 
printers. However, due to advances in computer hardware and software, business 
professionals and graphic artists now regularly create and produce complex, full color 
publications. This near commercial quality work may include black and white, 
grayscale, and color images, acquired from imaging devices such as desktop and 
15 handheld scanners, or digital still and video cameras. 

In order to include such images in a document, it is necessary for a software 
application being used to create the document to acquire image information from an 
imaging device. Under many conventional schemes, a user must first leave the 
application program used to create the document, locate and open a hardware driver 
20 for the imaging device, set various device options, acquire the image, make any 
desired modifications to the image, save the image to disk, close the hardware driver, 
return to the document application, and then locate and insert the image file from disk 
into the document. This process is both time consuming and tedious. Most business 
professionals, designers, or publishers would prefer a simpler approach that perhaps 
25 offers fewer control options, but is more efficient when all that is needed is to simply 
acquire an image with an imaging device and insert the image into a document. 
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In order to overcome some of the limitations associated with these 
conventional schemes, hardware and software developers began defining their own 
image acquisition interfaces that were specific to each application in which an image 
might be acquired. However, writing a separate driver for each imaging device that is 
5 desired to be supported by an application is clearly not an optimal solution. 
Similarly, it doesn't make sense to ask a hardware vendor to write a different driver to 
interface its imaging device with each different software application. More 
importantly, users should not have to deal with many unique application/device 
drivers in order to get their application programs to communicate with imaging 
10 devices. 

In 1991, a small group of hardware and software developers, lead by such 
companies as Hewlett Packard Corporation and Canon Corporation, proposed to 
simplify the image acquisition process through the development of a standard 
imaging device communication specification. The resulting specification has lead to 

15 the development of the TWAIN API and protocol, which enable application program 
developers to include support for various image acquisition devices without requiring 
special drivers for each different device and/or application. The TWAIN API and 
protocol (hereinafter often referred to simply as "TWAIN") is currently the industry 
standard for implementing the use of image acquisition devices in application 

20 programs. 

While TWAIN provides substantial benefits, it still has its limitations. For 
instance, applications that implement TWAIN generally use many built-in features, 
such as TWAIN's device selection dialog, or built-in dialogs for setting image 
capture parameters that are written by various vendors who manufacturer imaging 

25 devices that support the standard. Oftentimes, a user may desire to simply insert an 
image using default settings that will be appropriate for most image acquisitions, 
rather than having to select various settings through the use of dialogs. Thus, it 
would be desirable to provide means within any application program that will enable 
a user to capture and insert an image with minimal user input and/or knowledge of 

30 imaging device parameters. The TWAIN API is also quite complex, making it 
difficult for programmers with limited or no TWAIN experience to implement. Thus, 
it would also be desirable to enable an application program developer to be able to 
include support for image acquisition devices without requiring the developer to 
directly write procedure calls to the TWAIN API. 
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Summary of the Invention 

The present invention addresses the foregoing limitations of TWAIN and 
other prior art solutions to the problem of acquiring images for insertion in a 
document or other file by providing a system and associated methods for acquiring 
5 images from various imaging devices and inserting these acquired images into 
application program documents with minimal user interaction. The system augments 
TWAIN through the use of a special interface module API that allows the developers 
of various types of applications, including word processors, spreadsheets, and 
presentation design tools, to easily add the ability to insert images into documents or 

10 files that are created by such applications. The API provides means though which an 
application program can acquire images from any TWAIN compliant image 
acquisition device. In many instances, an application program developer can include 
support for TWAIN compliant devices through the use of a single procedure call, 
without requiring the developer to write any procedure calls to the TWAIN API. 

15 According to a first aspect of the invention, a method for inserting an image 

into an application program document is provided. The application program is 
running on a computer that is in communication with one or more image acquisition 
devices, such as scanners and digital cameras. The image is acquired or provided by 
an active image acquisition device, which can be a default device or one selected 

20 from a list of available devices generated by the system, and inserted into the 
application program document so that when the document is saved to a file, the 
captured image comprises a portion of the file. Furthermore, although it may be 
temporarily saved into a buffer, the captured image is never saved to a permanent 
file - that is a file that persists after the application program is closed or the computer 

25 is shut down during the process that inserts the image into document produced by the 
application program. 

According to a second aspect of the invention, a set of image capture 
capabilities of the active image acquisition device are determined, and a set of image 
capture parameters based in part on the determined capabilities is used to capture the 

30 image with the active device. The image acquisition device outputs image data 
corresponding to the captured image, which is then preferably converted into a 
compressed format, preferably using a "lossy" compression scheme known as the 
Joint Photographic Experts' Group (JPEG) format. The compressed image data are 
then inserted as an image into an application program document without requiring the 
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user to separately save the image as a file and then insert the image file into the 
document. The image data may also be enhanced prior to insertion (and 
compression) using a color correction scheme and/or a contrast/brightness correction 
scheme. In addition, the image may be automatically cropped so that only a desired 
5 portion of the image data are inserted into the document. 

According to a second aspect of the invention, the method allows the user to 
select the image acquisition device through a dialog that contains a drop-down menu 
control populated with a list of one or more image acquisition devices available to the 
user, thereby bypassing TWAIN's select source dialog, which is normally required 

10 when using TWAIN for acquiring images. The dialog also enables the user to select 
a predetermined resolution level, corresponding to whether the document is to be 
primarily viewed in printed form or as an online document (e.g., as a web page). 

According to another aspect of the invention, the method provides means for 
determining whether the selected image acquisition device can perform an automatic 

15 image scan. According to a first technique, a determination is made to whether the 
selected device can control its resolution in an X and Y direction, along with a 
determination of whether the device's built-in user interface can be bypassed. If the 
answer to all three of these determinations is true, then the device is deemed to 
support automatic scanning. According to a second technique, an error flag is set 

20 prior to attempting to automatically scan an image. If the automatic scanning is 
successful, the error flag is cleared; otherwise, the flag remains set. The error flag is 
stored, preferably in the operating system registry, so that an application program can 
disable automatic scanning if the error flag corresponding to a selected image 
acquisition device is set. If it is determined that the selected (or a default) device can 

25 perform automatic scanning, then a menu selection in the application program is 
enabled that allows the user to automatically scan and insert an image using a single 
action. 

According to another aspect of the invention, a method is provided for 
inserting a plurality of images into an application program document. An image 
30 source device dialog, corresponding to the device's built-in TWAIN user interface, is 
opened by user activation of a "Custom Insert" menu selection. The image source 
device dialog provides a user interface for selecting a plurality of images to be 
inserted into the document. The user selects the plurality of images to be inserted, 
and the image data for each selected image is compressed. The compressed image 
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data are then inserted into the application program as a plurality of images. The 
plurality of inserted images may be arranged in different layouts, depending on the 
nature of the application program document into which they are being inserted. For 
instance, in a word processor application, the images are preferably inserted in a tiled 
5 fashion. In a spreadsheet application, the images are preferably inserted as a plurality 
of cascaded images into the active spreadsheet. In a presentation design application, 
the images are preferably inserted as a plurality of new slides. 

According to yet another aspect of the invention, a system is provided for 
implementing the methods discussed above. The system comprises a computer that 

10 stores an application program in its memory. The computer is connected in 
communication with an image acquisition device that provides image data output. 
Also stored in the computer memory are a source driver module for the image 
acquisition device, and a source manager module. The source driver module provides 
a communication interface between the image acquisition device and the source 

15 manager module. An interface module, stored in the computer memory, is 
additionally provided, which allows communication between the application program 
and the source manager module. The interface module comprises an API that allows 
the application program to easily obtain image data from image acquisition devices 
and insert such data into an application program document as one or more images. 

20 The interface module also provides the ability to perform postprocessing 
enhancement of the image data, and for compressing the image data prior to inserting 
the image(s). 

Brief Description of the Drawing Figures 

The foregoing aspects and many of the attendant advantages of this invention 
25 will become more readily appreciated as the same becomes better understood by 
reference to the following detailed description, when taken in conjunction with the 
accompanying drawings, wherein: 

FIGURE 1 is a system level schematic block diagram illustrating the primary 
elements of TWAIN and illustrating how the elements interact when acquiring an 
30 image while using the TWAIN communication specification; 

FIGURE 2 is a block diagram illustrating the relationship between software 
elements of TWAIN and the layers these elements occupy under the TWAIN 
communication specification; 



MICR0I54-l-l/0154ap doc 



-6- 



FIGURE3 is a block diagram illustrating the entry points used for 
communicating between an application element and the source manager and source 
elements of TWAIN; 

FIGURE 4 is a schematic block diagram illustrating the seven states of 
5 TWAIN and describing the transitions that occur between these states; 

FIGURE 5 is a flowchart showing the logical operations performed during a 
TWAIN session; 

FIGURE 6 is a system level block diagram illustrating the components that an 
exemplary application program implementation of the present invention uses when 
10 acquiring an image from a TWAIN image acquisition device; 

FIGURE 7 is a flowchart illustrating the logic used when compiling a list of 
available image acquisition devices; 

FIGURE 8 is a flowchart illustrating the logic used when determining whether 
an image acquisition device can support automatic scanning; 
15 FIGURE 9 is a flowchart illustrating the logic used when acquiring an image 

with a TWAIN image acquisition device; 

FIGURE 10 is a flowchart illustrating the logic that an exemplary application 
program implementation of the invention performs when acquiring an image with a 
TWAIN image acquisition device; 
20 FIGURE 11A is a dialog that is presented to a user at the start of the 

invention's image acquisition process; 

FIGURE 11B is the dialog of FIGURE 11 A, showing activation of a drop- 
down menu listing different image acquisition devices available to a user; and 

FIGURE 12 is a schematic block diagram illustrating an exemplary computer 
25 system for practicing the present invention. 

Description of the Preferred Embodiment 
The present invention is an efficient system and associated method for 
acquiring images from various imaging devices and inserting these acquired images 
into application program documents. The system includes an interface module that 
30 comprises an API, which enables developers of various types of applications, 
including word processing, spreadsheet, and presentation design programs, to include 
support for the acquisition of images from various scanners, digital cameras, and 
image databases. The interface module API allows an application program to use 
much of the functionality built into the TWAIN API and protocol without requiring 
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the application program to make any procedure calls to the TWAIN API. However, 
the interface module API is still heavily dependent on TWAIN. Therefore, in order 
to more clearly describe how the invention is implemented, it is first necessary to 
discuss the TWAIN communication specification and explain how TWAIN operates. 
5 The following sections discuss fundamental aspects of TWAIN and 

techniques for implementing many of TWAIN's features through TWAIN's API 
Source Manager and Source, including exemplary computer code. It should be 
understood that the TWAIN communication specification and protocol were 
developed by others, completely apart from the present invention, and no inventive 

10 claim is made thereto in regard to the present invention. However, many of the 
aspects of the present invention discussed above are accomplished through the use of 
the invention's novel interface module API, which provides means for implementing 
TWAIN compliant image acquisition device based on the TWAIN API Source 
Manager and Source. A discussion of the interface module API and how it uses 

15 TWAIN begins with the section entitled "OFFICE 2000™ TWAIN implementation," 
which immediately follow the sections concerning TWAIN, below. 
The TWAIN Communication Specification 

The first version of the TWAIN communication specification was created by a 
small group of software and hardware developers in 199L TWAIN defines a 

20 standard software protocol and an API for communication between software 
applications and image acquisition devices (also known as data or image "sources"). 
The current version of the TWAIN specification (version 1.8) was ratified by the 
TWAIN working group on October 22, 1998. This specification is available from the 
TWAIN working group, which has a web site address of "www.twain.org." Portions 

25 of the current specification are incorporated herein within the following paragraphs, 
while the remainder of the TWAIN version 1.8 specification is incorporated herein by 
reference. 

The three key elements that comprise TWAIN are shown in FIGURE 1. 
These elements include application software 100 (the application), source manager 
30 software 102 (the Source Manager), and data source software 104 (the Source), all of 
which reside in a computer 106. Various image acquisition devices 107, such as a 
digital camera 108, a scanner 110, and an image database 112, may be connected to 
computer 106 via a communication hardware interface 113 that is specific to a 
particular device. For instance, a scanner may be connected to a computer via a small 
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computer system interface (SCSI), a parallel or serial port, a universal serial bus 
(USB) port, a "firewire" port (e.g., a port conforming to IEEE Specification 1394), or 
other types of hardware interfaces. Communication between the application software 
and image acquisition devices are handled by the Source and the Source Manager via 
5 TWAIN APIs 114 and 115. 

The Source controls the image acquisition device and is written by the device 
manufacturer to comply with TWAIN specifications. The Source Manager manages 
the interactions between the application and the Source. Computer code for 
implementing the Source Manager is provided in the TWAIN developer's toolkit, and 

10 comprises one or more software modules that are preferably stored as part of a 
computer operating system, or as part of the support code for an application program. 

The transfer of data between the application and an image acquisition device is 
made possible by the three software elements working together in communication 
under a four-layer architecture, as shown in FIGURE 2. The architecture includes an 

15 application layer 116, a protocol layer 118, an acquisition layer 120, and a device 
layer 122. 

A user's software application executes in the application layer. The TWAIN 
specification describes user interface guidelines for the application developer regarding 
how users should access TWAIN functionality and how a particular Source is selected. 

20 TWAIN is not concerned with how the application is implemented, and has no effect 
on any inter-application communication scheme that the application may use. 

TWAIN modules operate at the protocol layer. The protocol is the "language" 
spoken and syntax used by TWAIN. It implements precise instructions and 
communications required for the transfer of data. The protocol layer includes: (1) the 

25 portion of application software that provides the interface between the application and 
TWAIN; (2) the TWAIN Source Manager provided by TWAIN; and (3) the software 
included with the Source device to receive instructions from the Source Manager and 
transfer back data and return codes. 

The acquisition layer comprises acquisition devices, which may be physical 

30 (like a scanner or digital camera) or logical (like an image database). The software 
elements written to control acquisitions are called Sources and reside primarily in this 
layer. The Source transfers data for the application. It uses the format and transfer 
mechanism agreed upon by the Source and application. The Source always provides a 
built-in user interface that controls the device(s) the Source was written to drive. An 
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application can override the provision of the built-in interface and present its own user 
interface for acquisition, if desired. 

The device layer contains the traditional low level device drivers. The device 
drivers convert device specific commands into hardware commands and actions 
5 specific to the particular device the driver was written to accompany. Applications that 
use TWAIN no longer need to ship device drivers, because they are part of the Source. 
TWAIN is not concerned with the device layer at all. The Source hides the device 
layer from the application and provides the translation from TWAIN operations and 
interactions with the Source's user interface into the equivalent commands for the 

10 device driver that cause the device to behave as desired. 

As shown in FIGURE 3, communication between the TWAIN elements is 
possible through two entry points: a DSM_Entry( ) function 124 and a DS_Entry( ) 
function 126. The application communicates with the Source Manager through the 
Source Manager's only entry point, the DSM_Entry( ) function. The Source Manager 

15 communicates with the Source through its DSJEntry( ) function. 

The goal of the application in regard to the present invention is to acquire image 
data from a Source. However, applications cannot contact the Source directly. All 
requests for data, capability information, error information, etc. must be handled 
through the Source Manager. Approximately 140 operations are defined by TWAIN. 

20 The application sends a request for an operation to the Source Manager and specifies 
which element, the Source Manager or the Source, is the final destination for each 
requested operation. 

The Source Manager provides the communication path between the application 
and the Source, supports the user's selection of a Source, and loads the Source for 

25 access by the application. Communications from the application to the Source 
Manager arrive in the DSM_Entry( ) entry point. If the destination in the DSMJEntry 
call is the Source Manager, the Source Manager processes the operation itself. If the 
destination in the DSM_Entry call is the Source, the Source Manager translates the 
parameter list of information, removes the destination parameter and calls the 

30 appropriate Source. To reach the Source, the Source Manager calls the Source's 
DS JEntry( ) function. TWAIN requires each Source to have this entry point. 

The DS_Entry function call for the WINDOWS™ operating system is as 
follows: 
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TWJJINT16 FAR PASCAL DS_Entry 

(pTW_IDENTITY pOrigin, // source of message 
TW_UINT32 DG, // data group ID: DG_xxxx 
TW_UINT16 DAT, // data argument type: DAT_xxxx 
5 TWJJINT16 MSG, // message ID: MSG_xxxx 

TW_MEMREF pData // pointer to data 
) ; 

In addition, the Source Manager can initiate three operations that are not 
originated or requested by the application. These operation "triplets" exist just for 

10 Source Manager to Source communications and are executed by the Source Manager 
while it is displaying its Select Source dialog box. The operations are used to identify 
the available Sources and to open or close Sources. The Source Manager for 
WINDOWS is a Dynamic Link Library (DLL), that allows the Source Manager to 
manage simultaneous sessions between many applications with many Sources (i.e., 

15 the same instance of the Source Manager can be shared by multiple applications). 
The Use of Operation Triplets 

The DSM_Entry( ) and DS_Entry( ) functions are used to communicate 
operations. An operation is an action that the application or Source Manager invokes. 
Typically, but not always, these operations involve using data or modifying data that 

20 are indicated by the last parameter (pData) in the function call. 

Table 1 illustrates the context in which the DSM_Entry( ) and DSJBntry( ) 
functions are used. 



TABLE 1 



From: 


To: 


Using this function 


The application 


The Source Manager 


DSMJEntry with the pDest 
parameter set to NULL 


The application 


The Source (via the 
Source Manager) 


DSM JSntry with the pDest 
parameter set to point to a valid 
structure that identifies the Source 


The Source Manager 


The Source 


DS_Entry 



The desired action is defined by an operation triplet passed as three 
25 parameters in the function call. Each triplet uniquely specifies a particular action. 
No operation is specified by more than a single triplet. The three parameters that 
make up the triplet are a Data Group parameter, a Data Argument Type, and a 
Message ID. Each parameter conveys specific information, as follows. 
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Data Group (DG_xxxx) 

Operations are divided into large categories by the Data Group identifier and 
include control operations, image operations, and audio operations. The control 
operations use a DG_CONTROL identifier. These operations involve control of the 
5 TWAIN session. An example where DG_CONTROL is used as the Data Group 
identifier is the operation to open the Source Manager (see below). The image 
operations use a DGJMAGE identifier. These operations work with image data. An 
example where DGJMAGE is used as a Data Group is an operation that requests the 
transfer of image data. The audio operations use a DG_AUDIO identifier. These 

10 operations work with audio data that are supported by some digital cameras. An 
example where DG_AUDIO is used as a Data Group is an operation that requests the 
transfer of audio data. 
Data Argument Type (DAT_xxxx) 

This parameter of the triplet identifies the type of data that is being passed or 

15 operated upon. The argument type may reference a data structure or a variable. 
There are many data argument types. One example is DATJDDENTITY. The 
DATJDENTITY type is used to identify a TWAIN element such as a Source. 

Recall from above that data are typically passed or modified through the 
pData parameter of the DSM_Entry and DS__Entry. In this case, the pData parameter 

20 would point to a data structure of type TWJDENTTTY. Notice that the data 
argument type begins with DAT_xxxx and the associated data structure begins with 
TW_xxxx and duplicates the second part of the name. This pattern is followed 
consistently for most data argument types and their data structures. 
Message ID (MSG_xxxx) 

25 This parameter identifies the action that the application or Source Manager 

wishes to have taken. There are many different messages such as MSG_GET or 
MSG_SET, but all begin with a prefix MSG_. 

Below are three examples of operation triplets: 

The triplet the application sends to the Source Manager to open the Source 
30 Manager module is: 

DG_CONTROL / DAT_PARENT / MSG_OPENDSM. 

The triplet that the application sends to instruct the Source Manager to display 
its Select Source dialog box and thus allow the user to select the Source from which 
data will be obtained is: 
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DG__CONTROL / DAT_E)ENTITY / MSG_USERSELECT 

The triplet the application sends to transfer data from the Source into a file is: 

DG_IMAGE / DAT JMAGEHLEXFER / MSG_GET 
The State-Based Protocol 
5 The application, Source Manager, and Source must communicate to manage 

the acquisition of image data. It is logical that this process must occur in a particular 
sequence. For example, the application cannot successfully request the transfer of 
data from a Source before the Source Manager is loaded and prepared to 
communicate the request. 
10 To ensure the sequence is executed correctly, the TWAIN protocol defines 

seven states that exist in TWAIN sessions. A session is the period during which an 
application is connected to a particular Source via the Source Manager. The period 
during which the application is connected to the Source Manager is another unique 
session. At a given point in a session, the TWAIN elements of Source Manager and 
15 Source each occupy a particular state. Transitions to a new state are caused by 
operations requested by the application or Source and can be in a forward or 
backward direction. Most transitions are single-state transitions. For example, in 
general, an operation moves the Source Manager from State 1 to State 2, not from 
State 1 to State 3. (There are situations where a two-state transition may occur, but 
20 they are not discussed here). 

When viewing the state-based protocol, it is helpful to remember that 
States 1,2, and 3 are occupied only by the Source Manager; and that the Source 
Manager never occupies a state greater than State 3. Conversely, States 4, 5, 6, and 7 
are occupied exclusively by Sources. A Source never has a state less than 4 if it is 
25 open, and if it is closed, it has no state. If an application uses multiple Sources, each 
connection is a separate session and each open Source "resides" in its own state 
without regard for what state the other Sources are in. 

The various states are shown in FIGURE 4, and behave as follows. 
State 1 - Pre-Session 

30 The Source Manager "resides" in State 1 before the application establishes a 

session with it. At this point, the Source Manager code has been installed on a hard 
drive or other medium, but typically is not yet loaded into memory. The only case 
where the Source Manager could already be loaded and running is when another 
application is already running an instance of the Source Manager DLL. If that 
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situation exists, the Source Manager will be in State 2 or 3 relative to the application 
that loaded it. 

State 2 - Source Manager Loaded 

The Source Manager is now loaded into memory, but is not yet open. At this 
5 time, the Source Manager is prepared to accept other operation triplets from the 
application. 

State 3 - Source Manager Open 

The Source Manager is open and ready to manage Sources, i.e., to provide 
lists of Sources, to open Sources, and to close Sources. The Source Manager will 

10 remain in State 3 for the remainder of the session until it is closed. The Source 
Manager refuses to be closed while the application has any Sources open. 
State 4 - Source Open 

The Source has been loaded and opened by the Source Manager in response to 
an operation from the application and is ready to receive operations. The Source 

15 should have verified that sufficient resources exist for it to run (i.e., that sufficient 
memory is free, the device is available, etc.). The application can inquire about the 
Source's capabilities (i.e., levels of resolution, support for color or black and white 
images, automatic document feeder availability, etc.). The application can also set 
those capabilities to desired settings. For example, using the application, a user may 

20 restrict a Source capable of providing color images to transferring only black and 
white images. 

An inquiry about a capability can occur while the Source is in States 4, 5, 6, 
or 7. But, an application can set a capability only in State 4, unless a special 
permission is negotiated between the application and Source. 
25 State 5 - Source Enabled 

The Source has been enabled by an operation from the application via the 
Source Manager and is ready for user-enabled transfers. If the application has 
allowed the Source to display its user interface, the Source will do so when it enters 
State 5. 

30 State 6 - Transfer is Ready 

The Source is ready to transfer one or more data items (images) to the 
application. The transition from State 5 to 6 is triggered by the Source notifying the 
application that the transfer is ready. Before initiating the transfer, the application 
must acquire information about the image (resolution, image size, etc.). If the Source 
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supports audio, then before transferring the image, the application must transfer all 
the audio snippets that are associated with the image. It is possible for more than one 
image to be transferred in succession. 
State 7 - Transferring 

The Source is transferring the image to the application using the transfer 
mechanism negotiated during State 4. The transfer will either complete successfully 
or terminate prematurely. The Source sends the appropriate Return Code indicating 
the outcome. Once the Source indicates that the transfer is completed, the application 
must acknowledge the end of the transfer. 
Modifying an Application to Support TWAIN 

In order to implement a TWAIN compliant device in an application, it is 
necessary to include the TWAIN.H header file that is shipped with this TWAIN 
Developer's Toolkit. This header file contains all of the critical definitions needed 
for writing a TWAIN compliant application or Source. 

The TWAIN.H header file contains: 

Category Prefix for each item 
Data Groups DG_ 
Data Argument Types D AT_ 
Messages MSG_ 

Capabilities CAP_, ICAP_, or ACAP__ 

Return Codes TWRC_ 

Condition Codes TWCC_ 

Type Definitions TW_ 

Structure Definitions TW_ 

DSM_Entry( ) and DS JEntry( ) entry points 

In addition, there are many constants defined in TWAIN.H that are not listed 

here. 

It is also necessary to modify the application event loop (i.e., message loop). 
Events include activities such as key clicks, mouse events, periodic events, 
accelerators, etc. (On Microsoft Corporation's WINDOWS graphical user interface 
operating system, these actions are called messages, but TWAIN uses the term 
"messages" to describe the third parameter of an operation triplet. Therefore, these 
key clicks, etc. will be referred to as events in this section.) Every TWAIN compliant 
application needs an event loop. 
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During a TWAIN session, the application opens one or more Sources. 
However, even if several Sources are open, the application should only have one 
Source enabled at any given time, corresponding to the Source from which the user is 
attempting to acquire image data. Altering the event loop serves three purposes: 
5 (1) passing events from the application to the Source so the latter can respond to them; 
(2) notifying the application when the Source is ready to transfer data or have its user 
interface disabled; and (3) notifying the application when a device event occurs. 

While a Source is enabled, all events are sent to the application's event loop. 
Some of the events may belong to the application, but others belong to the enabled 
10 Source. To ensure that the Source receives and processes its events, the following 
changes are required: 

The application must send all events that it receives in its event loop to the 
Source as long as the Source is enabled. The application uses the following triplet to 
perform this function: 
1 5 DG_CONTROL / DAT J3VENT / MSG_PROCESSEVENT 

The TWJBVENT data structure used is as follows: 

typedef struct { 

TW_MEMREF pEvent; /* Windows pMSG or MAC pEvent 

*/ 

20 TW_UINT16 TWMessage; /* TW message from Source 

to */ 

/* the application */ 
} TWJEVENT, FAR *pTW_EVENT; 

The pEvent field points to the message structure. 

25 The Source receives the event from the Source Manager and determines if the 

event belongs to it. Dlf it does, the Source processes the event and then sets the Return 
Code to TWRC_DSEVENT to indicate it was a Source event. In addition, the Source 
should set the TWMessage field of the TW_EVENT structure to MSG^NULL. If it 
does not, the Source sets the Return Code to TWRC_NOTDSEVENT, meaning the 

30 event is not a Source event. In addition, it should set the TWMessage field of the 
TWJEVENT structure to MSG_NULL. The application receives this information from 
DSMJEntry and should process the event in its event loop, as it normally would. 

When the Source has data ready for a data transfer or it wishes to request that 
its user interface be disabled, it needs to communicate this information to the 

35 application asynchronously. These notifications appear in the application's event loop. 
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They are contained in the TW_EVENT.TWMessage field. The four notices of interest 
are: 

MSG_XFERREADY to indicate data are ready for transfer; 

MSG_CLOSEDSREQ to request that the Source's user interface be disabled; 
5 MSG_CLOSEDSOK to request that the Source's user interface be disabled (a 

special case for use with DG_CONTROL / DATJJSERINTERFACE / 
MSG JBNABLEDSUIONLY) ; and 

MSG_DEVICEEVENT to report that a device event has occurred. 

Therefore, the application's event loop should always check the 
10 TW_EVENT.TWMessage field following a DG_CONTROL / DATJEVENT / 
MSG_PROCESSEVENT call to determine if it is the simple MSG_NULL or critical 
MSG_XFERREADY or MSG__CLOSEDSREQ. 

The following code illustrates typical modifications needed in a WINDOWS 
application to support TWAIN connected Sources. 

15 TW_EVENT twEvent; 

TW_INT16 rc; 

while (GetMessage ( (LPMSG) &msg, NULL, 0, 0) ) 
{ 

if Source is enabled 
20 { 

twEvent . pEvent = ( TW__MEMREF ) &msg ; 
twEvent .TWMessage = MSG„NULL ; 
rc = (*pDSM_Entry) (pAppId, 

pSourceld, 

25 DG__CONTROL , 

DAT_EVENT, 
MSG_PROCESSEVENT , 
( TW_MEMREF ) & twEvent ) ; 
// check for message from Source 
30 switch (twEvent .TWMessage) 

{ 

case MSG_XFERREADY : 

SetupAndTransfer Image (NULL) ; 
break; 

35 case MSG__CLOSEDSREQ : 

DisableAndCloseSource (NULL) ; 
break; 
case MSG_NULL: 

//no message was returned from 
40 the source break; 

} 
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if (rc == TWRC_NOTDSEVENT) 
{ 

Trans lateMessage ( (LPMSG) &msg) ; 
DispatchMessage { (LPMSG) &msg) ; 

} 



} 



The DSM Entry Call and Available Operation Triplets 

As described in the Technical Overview chapter of the TWAIN specification, 
10 all actions that the application invokes on the Source Manager or Source are routed 
through the Source Manager. The application passes the request for the action to the 
Source Manager via the DSM_Entry function call, which contains an operation triplet 
describing the requested action. In code form, the DSM_Entry function for the 
WINDOWS graphical user interface operating system is of the following form: 

15 TW_UINT16 FAR PASCAL DSM_Entry 

{ p TW_ I DENT I T Y pOrigin, // source of 
message 

pTW_IDENTITY pDest, // destination of 
message 

20 TW_UINT3 2 DG, // data group ID: DG__xxxx 

TW_UINT16 DAT, // data argument type: 
DAT_xxxx 

TWJCJINT16 MSG, // message ID: MSG_xxxx 
TW_MEMREF pData // pointer to data 
25 ); 

The DG, DAT, and MSG parameters contain the operation triplet. The pOrigin 
parameter references the application's TWJQDENTITY structure. The contents of this 
structure must not be changed by the application from the time the connection is made 
with the Source Manager until it is closed. The pDest parameter should be set to 
30 NULL if the operation's final destination is the Source Manager. Otherwise, this 
parameter should be set to point to a valid TW_JDENTITY structure for an open 
Source. 

DG_xxxx is the Data Group of the operation. Currently, only DG_CONTROL, 
DGJMAGE, and DG_AUDIO are defined by TWAIN. Custom Data Groups can be 
35 defined. 

DAT_xxxx is a designator that uniquely identifies the type of data "object" 
(structure or variable) referenced by pData. 

MSG_xxxx is a message that specifies the action to be taken. 
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pData refers to the TW__xxxx structure or variable that will be used during the 
operation. Its type is specified by the DAT_xxxx entry. This parameter should always be 
typecast to TWJVffiMREF when it is being referenced. 
Controlling a TWAIN Session from within an Application 
5 FIGURE 5 is a flowchart disclosing the logical steps that are preferably used 

when implementing TWAIN within an application. The process starts in a block 200, 
which loads the Source Manager and gets the DSM_Entry point, which represents the 
transition from State 1 to 2. There are no TWAIN operations used for this transition. 
For a WINDOWS application, the TWA1N.DLL (or TWAIN32.DLL) is loaded using 

10 the LoadLibrary( ) routine. The DSM_Entry can be obtained by using the 
GetProcAddress( ) call. 

Once the Source Manager has been loaded, it must be opened by the 
application, which occurs in a block 202. The Source Manager is opened by a single 
triplet operation, DG_CONTROL / DAT_PARENT / MSG_OPENDSM. A 

15 WINDOWS application may open the Source Manager by using DSM_Entry, as 
follows: 

TW_UINT16 rc; 

rc = (*pDSM_Entry) (&AppID, 

NULL, 

20 DG_CONTROL, 

DAT_PARENT, 
MSG_OPENDSM, 
(TW„MEMREF) SchWnd) ; 

The pOrigin parameter (&AppED) points to a TWJDENTITY structure, 
25 while the pDest parameter should be set to NULL, and the pData parameter points to 
the application's main window handle (hWnd). The Source Manager will maintain a 
copy of this window handle for posting messages back to the application. 

The application must allocate a structure of type TW_IDENTITY and fill in 
all fields except for the ID field. Once the structure is prepared, the pOrigin 
30 parameter points at that structure. During the MSG_OPENDSM operation, the 
Source Manager fills in the ID field with a unique identifier of the application. The 
value of this identifier is only valid while the application is connected to the Source 
Manager. The application must save the entire structure. From then on, the structure 
will be referred to by the pOrigin parameter to identify the application in every call 
35 the application makes to DSM_Entry( ). 
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The TW_IDENTITY structure is defined in the TWAIN.H header file, and 
looks like this: 

/* DAT_I DENT I T Y Identifies the program/ library/code 

/* resource. */ 

typedef struct { 

TW_UINT32 Id; /* Unique number for 
identification*/ 
TW_VERSION Version; 
TW_UINT16 ProtocolMajor; 
TWJJINT16 ProtocolMinor; 

TWJJINT32 SupportedGroups; /*Bit field OR 
combination */ 
/*of DG_constants found in */ 
/*the TWAIN . H file */ 
TW_STR3 2 Manufacturer; 
TW__STR32 ProductFamily; 
TWJSTR32 ProductName; 
} TW_IDENTITY , FAR * pTW__I DENT I TY ; 

20 The following is an example of WINDOWS code that can be used to initialize 

the application's TWJDENTITY structure. 

TW_I DENT I TY AppID; // App ' s identity structure 
AppID. Id =0; // Initialize to 0 (Source 
Manager 

25 // will assign real value) 

AppID. Vers ion. Ma jorNum = 3; //Your app ' s 

version number 

AppID. Vers ion. MinorNum = 5; 

AppID. Vers ion. Language = TWLG_ENGL I S H_U S A ; 
30 AppID. Version. Country = TWCYJJSA; 

lstrcpy (AppID. Version. Info, "Your App ' s 
Version String"); 

AppID. ProtocolMajor = TWON_PROTOCOLMA JOR ; 

AppID. ProtocolMinor = TWON_PROTOCOLMINOR ; 
35 AppID. SupportedGroups = DG_IMAGE | DG_CONTROL; 

lstrcpy (App ID. Manufacturer, "App" s 

Manufacturer" ) ; 

lstrcpy (AppID . ProductFamily, "App ' s Product 
Family" ) ; 

40 lstrcpy (AppID . ProductName, "Specific App 

Product Name"); 



*/ 

5 



10 
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At this point, the Source Manager is open and available to assist the 
application in selection of the desired Source, which occurs in a block 204. This step 
is performed by a single operation triplet, DECONTROL / DAT_IDENTITY / 
MSG_USERSELECT. 
5 The pOrigin parameter should be set to point to the application's 

TWJDENTITY structure. The desired data type should be specified by the 
application, which was done when the SupportedGroups field was initialized in the 
application's TWJDENTITY structure, causing the Source Manager to make 
available for selection by the user only those Sources that can provide the requested 

10 data type(s). All other Sources are grayed out. (Note, if more than one data type 
were available, for example, image and text, and the application wanted to accept 
both types of data, it would do a bit-wise OR of the types' constants and place the 
results into the SupportedGroups field.) 

The pDest parameter should be set to NULL. 

15 The pData parameter should be set to point to a structure of type 

TW JDENTITY. The application must allocate this structure prior to making the call to 
DSM_Entry. Once the structure is allocated, the application must set the ID field to zero 
and set the ProductName field to the null string ("\0"). (If the application wants a 
specific Source to be highlighted in the Select Source dialog box, other than the system 

20 default, it can enter the ProductName of that Source into the ProductName field instead 
of null The system default Source and other available Sources can be determined by 
using the DECONTROL / DAT JDENTTTY / MSG_GETDEFAULT, MSG_GETFIRST 
and MSG_GETNEXT operations.) 

Additional fields of the structure are filled in by the Source Manager during 

25 this operation to identify the selected Source. The application should keep a copy of 
this updated structure after completing this call. 

The most common approach for selecting the Source is to use the Source 
Manager's Select Source dialog box. This dialog box is typically displayed when the 
user clicks on a Select Source option in the application's menu. This process can be 

30 accomplished by the following steps. 

1. The application sends a DG_CONTROL / DATJDENT1TY / 
MSG_USERSELECT operation to the Source Manager to have it display its dialog box. 
The dialog box includes a list of all Sources that are installed on the system that can 
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provide data of the type specified by the application. The Source that is the system 
default is highlighted unless the application requests otherwise. 

2. The user selects a Source or presses the Cancel button. If no devices 
are available, the Select Source Dialog's Select/OK button will be grayed out and the 

5 user will have no choice but to select Cancel. 

3. The application must check the Return Code of DSM_Entry to 
determine the user's action. 

a. If TWRC_SUCCESS: the selected Source is listed in the 
TWJDENTETY structure pointed to by the pData parameter and is now the 

10 default Source. 

b. If TWRC_CANCEL: the user either clicked Cancel 
intentionally or had no other choice because no devices were listed. Do not 
attempt to open a Source. 

c. If TWRC_FAILURE: use the DG_CONTROL / DATJSTATUS / 
15 MSG_GET operation (sent to the Source Manager) to determine the cause of the 

failure. The most likely cause is insufficient memory. 

As an alternative to using the Source Manager's Select Source dialog, the 
application can provide its own method or dialog box for selecting a Source. For 
example, the application could simply select a Source without offering the user a 
20 choice. Further details relating to creating a user interface that can directly access the 
Sources connected to the computer on which the application is running are discussed 
below. 

The next step in the process is performed in a block 206, which opens the 
selected Source. A single triplet operation is used, DG_CONTROL / D ATJOENITTY / 
25 MSG_OPENDS. The pOrigin parameter points to the application's TW_IDENTITY 
structure. The pDest parameter should be set to NULL. 

The pData parameter points to a structure of type TWJODENTITY. Typically, 
this parameter points to the application's copy of the Source's TWJQDENTITY 
structure filled in during the MSG_USERSELECT operation previously performed. 
30 However, if the application wishes to have the Source Manager simply open the default 
Source, it can do this by setting the TW_IDENTITY.ProductName field to "\0" (null 
string) and the TW_IDENTITY.Id field to zero. 

During the MSG_OPENDS operation, the Source Manager assigns a unique 
identifier to the Source and records it in the TWJDDENTITY.Id field. The resulting 
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TW_IDENTITY structure should be copied. Once the Source is opened, the 
application points to this resulting structure via the pDest parameter on every call that 
the application makes to DSM_Entry, where the desired destination is this Source. 

At this point, the application has a structure identifying the open Source. 
5 Operations can now be directed from the application to that Source. The next step is 
performed in a block 208, wherein the capabilities of the Source are negotiated. To 
receive a single image from the Source, only one capability, CAP_XFERCOUNT, 
must be negotiated. All other negotiation relating to capabilities is optional. 

There are two triplet operations used to negotiate capabilities: DG_CONTROL / 
10 DATCAPABUJTY / MSG_GET and DG_CONTROL / DAT„CAP ABILITY / 
MSGJSET. The pOrigin parameter points to the application's TWJDENTITY 
structure, and the pDest parameter points to the desired Source's TWJDENTITY 
structure. The Source Manager will receive the DSM_Entry call, recognize that the 
destination is a Source rather than itself, and pass the operation along to the Source via 
15 the DS_Entry function. The pData parameter points to a structure of type 
TW_CAP ABILITY. 

The definition of TW_CAP ABILITY is: 

typedef struct { 

TW_UINT16 Cap; /* ID of capability to get or 
20 set */ 

TW_UINT16 ConType; /* TWONJDNEVALUE , 

TWON__RANGE , */ 

/* TWON_ENUMERAT I ON or 

TWON_ARRAY */ 

25 TW__HANDLE hContainer; /* Handle to container of 

type */ 

/* ConType */ 
} TW_C APAB I L I TY , FAR *pTW_CAPABILITY ; 

The Source allocates the container structure pointed to by the hContainer field 
30 when called by the MSG_GET operation. The application allocates it when calling 
with the MSG_SET operation. Regardless of who allocated it, the application 
deallocates the structure either when the operation is completed or when the application 
no longer needs to maintain the information. 

Since Sources are not required to support all capabilities, the MSG_GET 
35 operation can be used to determine if a particular TWAIN defined capability is 
supported by a Source. The application needs to set the Cap field of the 
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TW_CAP ABILITY structure to the identifier representing the capability of interest. 
The constants identifying each capability are listed in the TWAIN.H file. If the 
capability is supported and the operation is successful, it returns the Current, Default, 
and Available values. These values reflect previous MSG_SET operations on the 
5 capability, which may have altered them from the TWAIN default values for the 
capability. 

This MSG_GET operation may fail due to several causes. If the capability is 
not supported by the Source, the Return Code will be TWRCJFAILURE and the 
condition code will be one of the following: 
10 TWCC„CAPUNSUPPORTED: capability not supported by Source, 

TWCC_CAPBADOPERATION: operation not supported by capability, or 

TWCC_CAPSEQERROR: capability has dependency on other capability. 

Applications should be prepared to receive the condition code 
TWCC_BADCAP from Sources written prior to TWAIN 1.7, which maps to any of 
15 the three situations mentioned above. 

The MSG_SET operation changes the current or available value(s) of the 
specified capability to those requested by the application. The application may 
choose to set just the capability's current value or it may specify a list of values for 
the Source to use as the complete set of available values for that capability. 
20 A Source is not required to limit values based on the application's request, 

although it is strongly recommended that they do so. Thus, certain Sources 
corresponding to specific hardware devices may not limit capabilities based on an 
application's request. If the return code indicates TWRCJFAILURE, check the 
condition code. A code of TWCCJ3 AD VALUE can mean that the application sent 
25 an invalid value for this Source's range; (2) the Source does not allow the setting of 
this capability; and (3) the Source doesn't allow the type of container used by the 
application to set this capability. 

Capability negotiation gives the application developer power to guide the 
Source and control the images they receive from the Source. The negotiation 
30 typically occurs during State 4. 

In order to illustrate how capabilities may be negotiated, an example of how 
to set the capability to specify the number of images the application can transfer is 
presented below. This example illustrates only one very basic capability and 
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container structure. More specific details concerning capability negotiations are 
available in Chapter 4 of the TWAIN 1 .8 specification. 

The capability that specifies how many images an application can receive 
during a TWAIN session is CAP_XFERCOUNT. All Sources must support this 
5 capability. Possible values for CAP_XFERCOUNT are: 

TABLE 2 



Value: 


Description: 


1 


Application wants to receive a single image. 


greater than 1 


Application wants to receive this specific number of images. 


-1 


Application can accept any arbitrary number of images during the 
session. This is the default for this capability. 


0 


This value has no legitimate meaning and the application should not set 
the capability to this value. If a Source receives this value during a 
MSG_SET operation, it should maintain the Current Value without 
change and return TWRC JFAILURE and TWCC_B AD VALUE. 



The default value allows multiple images to be transferred. The following is a 
simple code example illustrating the setting of a capability and specifically showing 
how to limit the number of images to one. 

10 TW__C AP AB I L I T Y twCapability; 

TW_INT16 count; 
TW_STATUS twStatus; 
TW_UINT16 rc; 
pTW_ONEVALUE pval; 

15 

// Setup for MSG_SET for CAP_XFERCOUNT 

twCapability. Cap = CAP__XFERCOUNT ; 
twCapability. ConType = TWON_ONEVALUE ; 
twCapability .hContainer = GlobalAlloc (GHND, 
20 s i z eo f ( TW_ONEVALUE ) ) ; 

pval = (pTW__ONEVALUE) 

GlobalLock (twCapability .hContainer) ; 
pval->ItemType = TWTY_INT16; 

pval->Item = 1; //This app will only accept 1 image 
25 GlobalUnlock { twCapabi 1 i ty . hContainer ) ; 
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// Set the CAP_XFERCOUNT 

rc = (*pDSM_Entry) (&AppID, 

&SourceID, 

DECONTROL, 
5 DAT__C A P AB I L I T Y , 

MSG_SET, 

( TW_MEMREF) &twCapabili ty) ; 

GlobalFree( (HANDLE) twContainer . hContainer ) ; 

10 

// Check Return Codes 

//SUCCESS 

if (rc == TWRC_SUCCESS) 
//the value was set 
15 //APPROXIMATION MADE 

else if (rc == TWRC_CHECKSTATUS) 
{ 

//The value could not be matched exactly 
//MSG_GET to get the new current value 
20 twCapability. Cap = CAP_XFERCOUNT ; 

twCapability .ConType = TWONJDONTCARE16 ; 
//Source will specify 

twCapability .hContainer = NULL; //Source 
allocates and fills container 
25 rc = (*pDSM_Entry) UAppID, 

ScSourcelD, 

DECONTROL, 

DAT__CAPAB I L I TY , 

MSG_GET, 

30 (TW_MEMREF) & twCapability) ; 

//remember current value 

pval = (pTW_ONEVALUE) 

GlobalLock ( twCapability . hContainer) ; 

count = pval->Item; 
35 //free hContainer allocated by Source 

GlobalFree ( (HANDLE) twCapability . hContainer ) ; 

//MSG_SET FAILED 
else if (rc == TWRC_FAILURE) 
40 { 

//check Condition Code 

rc = (*pDSM_Entry) (&AppID, 

&SourceID, 
DG_CONTROL , 

45 DAT_STATUS , 

MSG_GET, 

(TW_MEMREF) &twStatus) ; 
switch (twStatus . Condi tionCode) 
{ 
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TWCC_BADCAP : 
TWCC_CAPUNSUPPORTED : 
TWCC_CAPBADOPERATION : 
TWCC_CAPSEQERROR : 
5 //Source does not support setting 

this cap 

//All Sources must support 

CAP_XFERCOUNT 

break; 

10 TWCCUBADDEST : 

//The Source specified by pSourcelD 

is not open break; 
TWCC_BADVALUE : 

//The value set was out of range for 
15 this Source 

//Use MSG_GET to determine what 

setting was made 

/ / See the TWRC_CHECKSTATUS case 
handled earlier 
20 break; 

TWCC_SEQERROR: 

//Operation invoked in invalid state 
break ; 

} 

25 } 

After the capabilities of the Source are negotiated, data can be requested to be 
acquired from the Source. This step is performed in a block 210, where the application 
enables the Source to show its user interface, if requested, and prepare to acquire data. A 
single operation triplet is used: DG„CONTROL / DAT_USEREMTERFACE / 
30 MSG_ENABLEDS. The pOrigin parameter points to the application's TW_IDENTITY 
structure. The pDest points to the Source's TWJDENTITY structure. The pData points 
to a structure of type TW_USERINTERFACE. 

The definition of TW_USERINTERFACE is: 

typedef struct { 
35 TW_BOOL ShowUI; 

TW_BOOL ModalUI; 

TW_HANDLE hParent; 
} TW_USERINTERFACE , FAR *pTW_USER INTERFACE ; 

The ShowUI field should be set to TRUE for the Source to display its user 
40 interface. The Source sets the ModalUI field to TRUE if its user interface is modal. 
If the interface is modeless, the field is set to FALSE. The application sets the 
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hParent field differently, depending on the platform on which the application runs. In 
the WINDOWS operating system, the application should associate a handle with the 
Window that is acting as the Source's parent. 

In response to the user choosing the application's Acquire menu option to 
5 initiate acquisition of an image with a selected Source, the application sends this 
operation to the Source to enable it. The application typically requests that the 
Source display the Source's user interface to assist the user in acquiring data. If the 
Source is told to display its user interface, it displays the user interface when it 
receives the operation triplet and sets the ModalUI field of the data structure 

10 appropriately. Sources must check the ShowUI field and return an error if they 
cannot support the specified mode. In other words, it is unacceptable for a source to 
ignore a ShowUI = FALSE request and still activate its user interface. Once the 
Source is enabled via the DG_CONTROL / DATJJSERINTERFACE/ 
MSGJENABLEDS operation, all events that enter the application's main event loop 

15 must be immediately forwarded to the Source. 

The Source is now working with the user to arrange the transfer of the desired 
data. Unlike all the earlier transitions, the Source, not the application, controls the 
transition from State 5 to State 6, which is represented by a block 212, wherein a 
transfer ready signal is provided by the Source. There are no operations from the 

20 application that are used. This transition is not triggered by the application sending 
an operation; instead, the Source causes the transition. It should be recalled that 
while the Source is enabled, the application is forwarding all events in its event loop 
to the Source by using the DG^CONTROL /DATjEVENT / MSG_PROCESSEVENT 
operation. The TWJEVENT data structure associated is as follows: 

25 typedef struct { 

TW_MEMREF pEvent; /^Windows pMSG or MAC pEvent 
*/ 

TW_UINT16 TWMessage; /*TW message from the 

Source to the application*/ 
30 } TW_EVENT, FAR *pTW_EVENT; 

The Source can set the TWMessage field to signal when the Source is ready to 
transfer data. Following each DG_CONTROL / DAT_EVENT / 

MSGJPROCESSEVENT operation, the application must check the TWMessage field. 
If it contains MSG_XFERREADY, the session is in State 6 and the Source will wait 
35 for the application to request the actual transfer of data. 
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If the Source indicates that it is ready, then it is ready to transfer data. This 
operation is performed by a block 214. At this point, the Source is waiting for the 
application to inquire about the image details, initiate the actual transfer, and, hence, 
transition the session from State 6 to 7. If the initiation (DGJMAGE / 
5 DAT_MAGENATIVEXFER / MSG_GET (see below)) fails, the session does not 
transition to State 7, but remains in State 6. 

Two operation triplets are used in TWAIN, DGJMAGE / DATJMAGEINFO / 
MSG_GET and DGJMAGE / DATJMAGENATIVEXFER / MSG_GET. For the 
DGJMAGE / DAT_MAGEINFO / MSG_GET operation, the pOrigin parameter points 
10 to the application's TWJDENTITY structure. The pDest points to the Source's 
TWJDENTITY structure, and the pData points to a structure of type TW JMAGEINFO. 
The definition of TW JMAGEINFO is: 

typedef struct { 

TW_FIX32 XResolution; 
15 TW_FIX32 YResolution; 

TW_INT32 ImageWidth; 

TW_INT32 ImageLength; 

TW_INT16 SamplesPerPixel; 

TW_INT16 BitsPerSample[8] ; 
20 TW_INT16 BitsPerPixel; 

TW__BOOL Planar; 

TW_INT16 PixelType; 

TWJJINT32 Compression; 
} TW__IMAGEINFO , FAR * p TW_ IMAGE INFO; 

25 The Source fills in information about the image that is to be transferred. The 

application uses this operation to get the information regardless of which transfer 
mode (Native, Disk File, or Buffered Memory) will be used to transfer the data. 

For the DG_MAGE / DAT JMAGENATIVEXFER / MSG_GET operation, the 
pOrigin parameter points to the application's TWJQDENTITY structure. The pDest 

30 parameter points to the Source's TWJDENTITY structure, and the pData parameter 
points to a TW_UINT32 variable. This operation is an exception to the typical 
pattern. On a WINDOWS application, the pData parameter is a pointer to a handle 
variable. For a 16-bit WINDOWS environment, the handle is stored in the low word 
of the 32-bit integer, and the upper word is set to zero. If running under the WIN32™ 

35 environment, this handle is a 32-bit window handle. The Source sets pHandle to 
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point to a device independent bitmap (DIB) that it allocates. The application is 
responsible for deallocating the memory block holding the Native format image. 

The application may want to inquire about the image data that it will be 
receiving, and the DGJMAGE / DATJMAGEINFO / MSG_GET operation allows this 
5 inquiry to occur. Other operations, such as DGJMAGE / DATJMAGELAYOUT / 
MSG_GET, provide additional information, which can be used to determine if the 
application actually wants to initiate the transfer. To actually transfer the data in the 
Native mode, the application invokes the DGJMAGE /DATJMAGENAHVEXFER / 
MSG_GET operation. The Native mode is the default transfer mode and is used 

10 unless a different mode was negotiated via the capabilities in State 4. For the Native 
mode transfer, the application only invokes this operation once per image. The 
Source returns the TWRC_XFERDONE value when the transfer is complete. This 
type of transfer cannot be aborted by the application once initiated. (Whether it can 
be aborted from the Source's user interface depends on the Source.) 

15 The following code provides an exemplary illustration of how to get 

information about the image that will be transferred and how to actually perform the 
transfer. This code segment is continued in the following section. 

// After receiving MSG_XFERREADY 
TW_UINT16 Trans ferNative Image ( ) 
20 { 

TW_IMAGE INFO twlmagelnfo; 
TWJJINT16 rc; 
TWJJINT32 hBitmap; 
TW_BOOL PendingXfers = TRUE; 
25 while (PendingXfers) 
{ 

rc = (*pDSM_Entry) (&AppId, 
ScSourceld, 
DG_IMAGE , 
30 DAT__IMAGEINFO , 

MSG_GET, 

(TW_MEMREF)&twImageInfo) ; 
if (rc == TWRC_SUCCESS) 

Examine the image information 
35 // Transfer the image natively 

hBitmap = NULL; 
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rc = (*pDSM_Entry) (&AppId, 
SourceId r 
DG_IMAGE, 

DAT__IMAGENATIVEXFER , 
5 MSG_GET, 

(TW_MEMREF)&HbITMAP) ; 
// Check the return code 
switch (rc) 
{ 

10 case TWRC_XFERDONE : 

// Notes: hBitmap points to a valid image Native 
image (DIB or 
// PICT) 

// The application is now responsible for 
15 deallocating the memory. 

// The source is currently in state 7. 

/ / The application must now acknowledge the end of 

the transfer, 

// determine if other transfers are pending and shut 
20 down the data 

// source. 

PendingXfers = DoEndXf er ( ) ; //Function found in 

code 

//example in next 
25 section 

break; 

case TWRC_CANCEL : 
// The user canceled the transfer. 
30 // hBitmap is an invalid handle but memory was 

allocated. 

// Application is responsible for deallocating the 
memory . 

// The source is still in state 7. 
35 // The application must check for pending transfers 

and shut down 
// the data source. 

PendingXfers = DoEndXf er ( ) ; //Function found in 

code 

40 //example in next 

section 

break; 
case TWRC_FAILURE : 
// The transfer failed for some reason. 
45 // hBitmap is invalid and no memory was allocated. 

/ / Condition code will contain more information as 
to the cause of 
// the failure. 
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// The state transition failed, the source is in 
state 6. 

// The image data are still pending. 
// The application should abort the transfer. 
5 DoAbortXf er (MSG_RESET) ; //Function in next 

section 

PendingXfers = FALSE; 
break; 

} 

10 } 
} 

//Check the return code 
switch (rc) 
{ 

15 case TWRC_XFERDONE : 

//hBitMap points to a valid Native Image (DIB 
or PICT) 

//The application is responsible for 
deallocating the memory 
20 //The source is in State 7 

/ /Acknowledge the end of the transfer 

goto LABEL_DO_ENDXFER //found in next 
section 
break; 

25 case TWRC_CANCEL : 

//The user canceled the transfer 

//hBitMap is invalid 

//The source is in State 7 

//Acknowledge the end of the transfer 
30 goto LABEL_DO_ENDXFER //found in next 

section 

break; 
case TWRC_FAILURE ; 

//The transfer failed 
35 //hBitMap is invalid and no memory was 

allocated 

/ /Check Condition Code for more information 
//The state transition failed, the source is in 
State 6 

40 //The image data are still pending 

//To abort the transfer 

goto LABEL_DO_ENDXFER //found in code 
example for 

//the next section 

45 break; 
} 
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While the transfer occurs, the session is in State 7. When the Source indicates 
via the Return Code that the transfer is done (TWRC_XFERDONE) or canceled 
(TWRC_CANCEL), the application needs to transition the session backwards. This 
step is performed in a block 216 using a single operation triplet, DG_CONTROL / 
5 DAT_PENDINGXFERS / MSGJ2NDXFER. The pOrigin points to the application's 
TWJDENTITY structure. The pDest points to the Source's TWJDENTTTY 
structure, and the pData points to a structure of type TW„PENDINGXFERS. 

The definition of TW_PENDINGXFERS is: 

typedef struct { 
10 TWJJINT16 Count; 

TW_UINT32 Reserved; 
} TW_PENDINGXFERS , FAR *pTW_PENDINGXFERS ; 

The DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXEER operation is 
sent by the application to the Source at the end of every transfer, successful or 
15 canceled, to indicate the application has received all the data it expected. After this 
operation returns, the application should examine the pData~>Count field to 
determine if there are more images waiting to be transferred. 

The following code is a continuation of the code example started in the State 6 
to 7 section above and illustrates an example of how to the transfer may be 
20 concluded. 

void DoEndXferO 
{ 

TW_PENDINGXFERS twPendingXf ers ; 
// If the return code from 
25 DG_IMAGE/DAT_IMAGENATIVEXFER/MSG_GET was 

// TWRC__CANCEL or TWRC_DONE 
// Acknowledge the end of the transfer 
rc = (*pDSH_Entry) (&AppId, 

Sourceld, 

30 DG_CONTROL , 

DAT_PENDINGXFERS , 
MSG_ENDXFER, 

(TW_MEMREF) &twPendingXf ers ) 

35 if (rc == TWRC_SUCCESS) 

{ 

/ / Check for additional pending xf ers 

if (twPendingXf ers .Count == 0) 

{ 
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// Source is now in state 5. NOTE THE 
IMPLIED STATE 

// TRANSITION! Disable and close the 
source and 

5 // return to Trans ferNative Image with a 

FALSE notifying 

// it to not attempt further image 
transfers . 

DisableAndCloseDS ( ) ; 
10 return (FALSE) ; 

} 

else 
{ 

// Source is in state 6 ready to transfer 
15 another image 

if want to transfer this image 
{ 

// returns to the caller, 
Trans ferNativelmage 
20 // and allows the next image to transfer 

return TRUE; 

else if want to abort and skip over this 
transfer 

{ 

25 // The current image will be skipped, 

and the 

// next, if exists will be acquired 
by returning 

// to Trans ferNativelmage 
30 if (DoAbortXf er (MSG_ENDXFER) > 0) 

return (TRUE) ; 
else 

return (FALSE) ; 

} 

35 } 
} 

} 

} 

TW_UINT16 DoAbortXf er (TWJJINT16 AbortType) 
40 { 

rc = (*pDSM_Entry) (&AppId, 

Sourceld, 
DG_CONTROL, 
DAT_PENDINGXFERS , 
45 MSG_ENDXFER, 

{ TW_MEMREF ) & twPendingXf er s ) ; 
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if (rc == TWRC__SUCCESS ) 
{ 

// If the next image is to be skipped, but 
subsequent images 
5 // are still to be acquired, the PendingXfers 

will receive 

// the MSG_ENDXFER, otherwise, PendingXfers 
will receive 
// MSG__RESET . 
10 rc = (*pDSMJEntry) (&AppId, 

Sourceld, 

DG__CONTROL , 

DAT_PENDINGXFERS , 

AbortType, 

15 (TW„MEMREF) &twPendingXf ers ) ; 

} 

} 

//To abort all pending transfers: 
LABEL_ABORT_ALL : 
20 { 

rc = (*pDSM_Entry) (&AppID, 

&SourceID, 

DG_CONTROL, 

DAT__PENDIMGXFERS , 
25 MSGJRESET, 

(TW_MEMREF) SctwPendingXf ers ) ; 
if (rc == TWRCJ3UCCESS) 

//Source is now in state 5 

} 

30 } 

Once the application has acquired all desired data from the Source, the 
application can disconnect the TWAIN session, which is performed in a block 218. 
To do this, the application transitions the states backwards until the first state is 
reached. In the previous section, the Source transitioned to State 5 when there were 

35 no more images to transfer (TW_PENDINGXFERS. Count = 0) or the application 
called the DG„CONTROL / DAT_PENDINGXFERS / MSG_RESET operation to 
purge all remaining transfers. To back out the remainder of the session three 
operations, some platform dependent code is used. 

A DG_CONTROL / DATJJSERINTERFACE / MSGJDISABLEDS 

40 operation is used to move from State 5 to State 4. The pOrigin parameter points to 
the application's TWJDENTITY structure, while the pDest parameter points to the 
Source's TWJDENTITY structure. The pData parameter points to a structure of 
type TWJJSERINTERFACE. 
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The definition of TW_USERINTERFACE is: 

typedef struct { 

TW_BOOL ShowUI; 

TWJBOOL ModalUI; 
5 TW_HANDLE hParent; 

} TW_USERINTERFACE, FAR *pTW_USERINTERFACE; 

Its contents are not used. 

If the Source's user interface was displayed, this operation causes the 
Source's user interface to close. The operation is sent by the application in response 

10 to a MSG_CLOSEDSREQ from the Source. This request from the Source appears in 
the TWMessage field of the TW_EVENT structure and is sent back from the 
DG.CONTROL / DATJEVENT / MSG_PROCESSEVENT operation used by the 
application to send events. 

If the application did not have the Source's user interface displayed, the 

15 application invokes this command when all transfers have been completed. In 
addition, the application could invoke this operation to transition back to State 4 if it 
wanted to modify one or more of the capability settings before acquiring more data. 

To move from State 4 to State 3, the DG_CONTROL / DATJDENTITY / 
MSG_CLOSEDS operation triplet is used. The pOrigin parameter points to the 

20 application's WJDENTITY structure. At this point, the pDest parameter should 
reference a NULL value (indicates destination is Source Manager). The pData points to a 
structure of type TWJDENTITY, which is the same TWJDENT1TY structure that is 
used throughout the session to direct operation triplets to this Source. 

When this operation is completed, the Source is closed. In a more complicated 

25 scenario, if the application had more than one Source open, it must close them all before 
closing the Source Manager. Once all Sources are closed and the application does not plan 
to initiate any other TWAIN session with another Source, the Source Manager should be 
closed by the application. 

To move from State 3 to State 2, a DG_CONTROL / DATJ>ARENT / 

30 MSG_CLOSEDSM operation triplet is used. The pOrigin parameter points to the 
application's TW_IDENTITY structure, and the pDest parameter should reference a NULL 
value (indicates destination is Source Manager). On the WINDOWS graphical user interface 
operating system, the pData parameter points to the window handle (hWnd) that acted as the 
Source's "parent." The variable is of type TW_INT32. For 16-bit WINDOWS, the handle is 
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stored in the lower word of the 32-bit integer, and the upper word is set to zero. If running 
under the WIN32 environment, this is a 32-bit window handle. 

Once the Source Manager has been closed, the application must unload the 
DLL from memory before continuing. This step can be done in WINDOWS by using 
5 FreeLibrary( hDSMLib), where hDSMLib is the handle to the Source Manager DLL 
returned from the call to LoadLibrary( ) discussed above. 

A summary of the simplest view of an application's TWAIN flow is shown below 
in TABLE 3. All TWAIN actions are initiated by a TWAIN command, either user initiated 
(Select Source and Acquire) or notification from the Source (MSG_XFERREADY and 
10 MSG_CLOSEDSREQ). 



TABLE 3 



Application Receives 


State 


Application Action 


Select Source... 


l->2 


Load Source Manager 




2->3 


DG_CONTROL / DAT_PARENT / MSG_OPENDSM 
DG_CONTROL / DAT^IDENTTTY / MSG_USERSELECT 




3->2 


DG_CONTROL / DAT_PARENT / MSGJXOSEDSM 




2->l 


Unload Source Manager 


Acquire. . . 


l->2 


Load Source Manager 




2->3 


DG_CONTROL / DAT_PARENT / MSG_OPENDSM 




3->4 


DG_CONTROL / DATJDENTTTY / MSG_OPENDS 
Capability Negotiation 




4->5 


DG_CONTROL / DAT JJSERINTERFACE /MSG_ENABLEDS 


MSG_XFERREADY 


6 


For each pending transfer: 
DGJMAGE / DAT_IMAGEINFO / MSG_GET 
DG_IMAGE / DAT_MAGELAYOUT / MSGJjET 
DECONTROL / DAT_CAP ABILITY / MSG_GETCURRENT 




6->7 


DG_IMAGE / DAT_IMAGExxxxXFER / MSG_GET 




7->6 


DG JX>NTR0L / DATJPENDINGXFERS / MSG_ENDXFER 




6->5 


Automatic transition to State 5 if W_PENDINGXFERS. Count 
equals 0. 


MSG_CLOSEDSREQ 


5->4 


DG_CONTROL / DAT JJSERINTERFACE / 
MSG_DISABLEDS 




4->3 


DG.CONTROL / DATJDENTTTY / MSG JXOSEDS 




3->2 


DG_CONTROL / DATJPARENT / MSG_CLOSEDSM 




2->l 


Unload the Source Manager 
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OFFICE 2000 TWAIN Implementation 

Details that are more specific to a preferred embodiment of the present invention, 
as implemented in Microsoft Corporation's OFFICE 2000™, are discussed in this 
section. The OFFICE 2000 product comprises a suite of application programs that share 
5 various resources, including DLLs. In regard to the present invention, OFFICE 2000 
enables its application programs to acquire and insert images from TWAIN compliant 
image acquisition devices through a special dynamic link library API module, called 
MSOTW9.DLL. As shown in FIGURE 6, MSOTW9.DLL API module 300 resides 
between an application 302 and a TWAIN.DLL API module 304, which handles the 

10 Source Manager functions discussed above. The MSOTW9.DLL API module supports 
communication between the application and TWAIN. The TWAIN.DLL API module 
communicates with one or more image acquisition devices 306 through one or more 
driver.ds modules 308, which contain the code for performing the Source functions 
discussed above. Alternately, a plurality of Source drivers may be stored in one or more 

15 DLL files. 

The driver.ds modules are hardware drivers that are specifically written to 
support a particular image acquisition device, or a particular set of devices. These 
driver modules are written so that they perform at least a minimum level of features 
defined by TWAIN, allowing a particular device for which the driver is written, to 

20 support any TWAIN compliant application program. For instance, Hewlett Packard 
Corporation manufacturers several scanners that have associated driver.ds files, 
which enable the use of such scanners in any application that is designed to support 
TWAIN compliant devices. 

The MSOTW9.DLL API module allows an application program to implement 

25 various features of TWAIN by providing an API that comprises a single entry point. 
In this way, it is not necessary for the application program to call any of the TWAIN 
calls available through the TWAIN.DLL API. The MSOTW9.DLL module also 
handles the necessary changes to the application's event loop, as discussed above, 
without requiring the event loop within the application to be altered. Furthermore, 

30 the MSOTW9.DLL API module provides functionality that is not directly available 
from the TWAIN.DLL API module, such as generating drop-down menu structures 
comprising a list of available image acquisition devices and verifying whether an 
image acquisition device can actually support automatic scanning. 
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In order to implement the features of the invention in accord with one 
preferred embodiment, it is necessary to install the MSOTW9.DLL API module, the 
TWA1N.DLL API module, and appropriate device driver files and/or libraries on a 
computer. Both the WINDOWS 98™ and WINDOWS NT™ operating systems can 
5 be installed with all the necessary TWAIN modules during their initial installation, or 
during a subsequent update. In addition to the TWAIN.DLL module, it may be 
necessary to install a TWAIN__32.DLL module, along with TWUNK_16.EXE and 
TWUNK_32.EXE files. The TWUNK files allow a programs and/or drivers written 
for a 16-bit environment to operate in a 32-bit environment. 

10 One of the objectives of the MSOTW9.DLL API module is to allow an 

application to automatically scan an image and insert the image into a document with 
minimal user input. Typically, in order to perform a scan under the prior art, it is 
necessary to invoke the TWAIN Source Manager select source dialog to select a 
device, and then to invoke a TWAIN compliant user interface for the selected image 

15 acquisition device that is provided by the manufacturer of the device, through the 
driver.ds file. This user interface commonly comprises one or more dialogs that 
contain various parameters that must be set in order to obtain an image. Although the 
use of such an interface allows specific capabilities and parameters to be set, it is often 
the case that a set of default parameters can be used to obtain acceptable results, in a 

20 much simpler fashion. 

In order to scan an image under the present invention, it is also necessary to 
select an available image acquisition device (even if only confirming a default image 
acquisition device). The MSOTW9.DLL API allows an application program user to 
select an available data acquisition device without having to use the normal TWAIN 

25 Source Manager Select Source dialog. The MSOTW9.DLL API provides a dialog 
(upon selection of an "Acquire Image" menu item in the application) that includes a 
drop-down list box, which is used for selecting an active image acquisition device 
from among a list of devices that is automatically generated by the API. 

The process for generating the list of available image acquisition devices is 

30 illustrated by the flowchart shown in FIGURE 7. The process begins with a decision 
block 400, which invokes a TWAIN API call to determine if any TWAIN compliant 
image acquisition devices (TWAIN devices) are available for use (i.e., connected to the 
computer and operating). If the answer to the query is yes, then a TWAIN API 
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procedure call is made in a block 402 to get the next (starting with a first) TWAIN 
device, as follows: 

// Get next Twain Device 

TWAIN_Entry( DATJDENTITY, MSG_GETNEXT, 

5 (TW_M E M RE F) &S ou rce I D) ; 

This TWAIN API call returns a pointer to a Source identifier (&SourceDD). 
The TWAIN API call also performs the function of a decision block 404, which 
queries to see if there are any more TWAIN devices. If the answer is no, then 
identification of the available TWAIN devices to be listed is completed. 

10 For each of the identified TWAIN devices, a first query is made in a decision 

block 406 to see if the device is listed in the operating system registry. If the device 
is listed, then various capabilities of the device (that are stored in the registry) are 
retrieved from the registry, and the process proceeds to a block 408. If the device is 
not listed in the registry, then a second query is made in a decision block 410 to 

15 determine if the device is listed in the MSOTW9.DLL resources (see below). If the 
device is listed in these resources, then various capabilities of the device are retrieved 
from the resources, and the process proceeds to block 408. If the answer to both of 
the queries in blocks 408 and 410 is no, then a determination is made to ascertain 
whether the device can support automatic scanning (autoscanning) in a block 412 (see 

20 below), whereupon the process proceeds to block 408. 

In block 408, the TWAIN device is added to a list of available TWAIN 
devices, which includes the identity of the device, along with an indication of whether 
it supports autoscanning. The process returns to block 402, where the previous steps 
are repeated until the answer to decision block 404 is no (i.e., there are no more 

25 devices to get). 

The process for determining whether a device has the capability to perform an 
autoscan is illustrated by the flowchart shown in FIGURE 8. An autoscan capable device 
can perform a scan and produce an image without requiring the user to enter the device's 
user interface, thereby allowing an application program to request the device to scan 

30 using a minimum amount of user input. Under some circumstance, this may require only 
a single user action after an initial "Acquirelmage" menu item selection. 
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The process begins in a decision block 414, where a query is made to 
determine if the device can control its resolution in the X direction, using the 
following code: 

// Check if device can alter its X Resolution 
5 mJwCapability.Cap = ICAP_XRESOLUTION; 

mJwCapability.ConType = TWON_DONTCARE 1 6; 
m_twCapabi!ity.hContainer= NULL; 
TWAIN_Entry( DAT_CAPAB!L!TY, MSG_GET, 

(TWJVIEMREF)&mJwCapability, &m_SourceID); 

10 If the device cannot control its resolution in the X direction, then the logic 

proceeds to a block 416, which provides a return parameter indicating that the device 
cannot autoscan. 

If the device can control its resolution in the X direction, then the logic 
proceeds to a decision block 418, where a query is made to determine if the device 
15 can control its resolution in the Y direction, using the following code: 

// Check if device can alter its Y Resolution 
mJwCapability.Cap = ICAP_YRESOLUTiON; 
mJwCapability.ConType = TWON_DONTCARE16; 
m JwCapability.hContainer = NULL; 
20 TWAIN_Entry( DAT_CAPABILITY, MSG_GET, 

(TW_MEMREF)&mJwCapability, &m_SourcelD); 

If the device cannot control its resolution in the Y direction, then the logic 
proceeds to block 416, which provides a return parameter indicating that the device 
cannot autoscan. 

25 If the device can control its resolution in both the X and Y directions, the logic 

proceeds to a decision block 420, where a query is made to determine if the device can 
turn its user interface off. In order to autoscan, the application must be able to bypass the 
built-in user interface for a device. The following code is used for this query: 

// Check if device can turn off its Ul. 
30 mJwCapability.Cap = CAP JJICONTROLLABLE; 

mJwCapability.ConType = TWON JDONTCARE 1 6; 
m JwCapability.hContainer = NULL; 

TWAIN_Entry( DAT_CAPABILITY, MSG_GET, 

(TW„MEMREF)&mJwCapability, &m_SourcelD); 
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If the device cannot turn off its user interface, then the logic proceeds to 
block 416, which provides a return parameter indicating that the device cannot 
autoscan. If the device can turn off its user interface, then the logic proceeds to a 
block 422, which provides a return parameter indicating that the device can autoscan. 
5 Bypassing the Source User Interface 

In addition to bypassing the Source Manager's Select Source dialog, the 
application may desire to bypass the Source's user interface. As discussed above, 
this is a necessary capability for performing an autoscan. 

To enable the Source without displaying its user interface, the DG_CONTROL / 
10 DATUSERINTERFACE / MSG_ENABLEDS operation is used. The ShowUI field of 
the TWJJSERINTERFACE structure is set to FALSE. 

When the command is received and accepted (TWRC_SUCCESS), the Source 
does not display a user interface, but is armed to begin capturing data. For example, 
in a flatbed scanner, the light bar is energized and begins to move. A handheld 
15 scanner is armed and ready to acquire data when the "go" button is pressed on the 
scanner. Other devices may respond differently, but all will either begin acquisition 
immediately or be armed to begin acquiring data as soon as the user interacts with the 
device appropriately. 

It is essential that capability negotiation used with the Source's user interface 
20 be bypassed. Since the Source's user interface is not displayed, the user will have no 
means for setting various image capture parameters. Unless default values are 
acceptable, current values for all image acquisition and control parameters must be 
negotiated before the Source is enabled, i.e., while the session is in State 4. 

When WJJSERINTERFACEShowUI is set to FALSE, the application is still 
25 required to pass all events to the Source (via the DG_CONTR017 DATJEVENT / 
MSGJ>ROCESSEVENT operation) while the Source is enabled. The Source must 
display the minimum possible user interface containing only those controls required to 
make the device useful in context. In general, this means that no user interface is 
displayed; however, certain devices may still require a trigger to initiate the scan. By 
30 default, the Source still displays a progress indicator during the acquisition. The 
application can suppress this display by setting CAPJNDICATORS to FALSE, if the 
Source allows that option. 

The Source still displays errors and other messages related to the operation of its 
device, since these functions cannot be disabled. The Source still sends the application a 
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MSG_XFERREADY notice when the data are ready to be transferred. The Source may 
or may not send a MSG_CLOSEDSREQ to the application asking to be closed, since this 
message is often user initiated. Therefore, after the Source has returned to State 5 
(following the DG.CONTROL / DATJPENDINGXFER5 / MSG_ENDXFER operation 
5 and the TWJPENDINGXFERS.Count = 0), the application can send the DG_CONTROL / 
DAT JJSER1NTERFACE / MSG J3IS ABLEDS operation. 

It should be noted that some Sources may display their user interface even when 
ShowUI is set to FALSE. An application can determine whether ShowUI can be set by 
interrogating the CAP_UICONTROLLABLE capability. If CAP_UICONTROLLABLE 

10 returns FALSE, but the ShowUI input value is set to FALSE in an activation of 
DG_CONTROL / DAT_USERINTERFACE / MSG_ENABLEDS, the enable DS operation 
returns TWRC_CHECKSTATUS and displays the UI regardless. Therefore, an application 
that requires that the UI be disabled should interrogate CAP_UICONTROLLABLE before 
issuing MSG_ENABLEDS. 

15 FIGURE 9 includes a flowchart illustrating the logic used when acquiring an 

image. The process starts in a block 500, where a user selects a device from a drop- 
down menu. The drop-down menu is generated from this list of available TWAIN 
devices found above (FIGURE 7). 

After a device is selected by the user, the registry is checked to see if the 

20 autoscan error bit is set for the chosen device in a decision block 502. The autoscan 
error bit is used to inform the application whether or not the selected device can be used 
for autoscanning. If the autoscan error bit is set, a block 504 disables the application 
from performing autoscanning during future operations. 

The logic next proceeds to a block 506, where the user selects the scanning 

25 operation that is to be performed. The user is presented with an "Insert" option and a 
"Custom Insert" option, in a preferred embodiment. The "Custom Insert" option is 
selected when the user wants to control image capture parameters, such as image 
resolution, special cropping, etc. The "Insert" option is selected when the user 
desires to automatically scan and insert (autoscan) an image without requiring any 

30 additional settings be selected. 

A decision block 508 determines if the "Insert" (autoscan) option is selected. 
If this option was not selected, TWAIN's normal image acquisition process is used, 
beginning in a block 510, which displays the selected device's built-in user interface. 
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The user can then select various image capture parameters to control capture of the 
image. Display of the built-in user interface is performed with the following code: 

// Tell device to turn on its Ul 
mJwUI.ShowUUTRUE; 
5 TWAIN_Entry( DATJJSERINTERFACE, MSG_ENABLEDS, 

TWJVIEMREF)&m_twUI, &m_SourcelD); 

If automatic insert is selected, the logic proceeds to a block 512, where an 
autoscan error flag is set in the registry. The autoscan error flag is separate from and in 
addition to the autoscan error bit discussed above, and is used to identify whether or not 

10 the device supports autoscanning through an attempted use of the device for 
autoscanning. With reference to FIGURE 8 and the discussion above, if the answer to 
any of the queries in decision blocks 414, 418, or 420 is no, the device is not capable of 
autoscanning. However, there are some instances where the answer to all of these 
queries for a given device will be yes (true), even though the device is not capable of 

15 performing an autoscan. This is the reason for setting the autoscan error flag here. If the 
autoscan operations discussed below are successful, the autoscan error flag will be 
cleared, and autoscanning of the device will be confirmed. In contrast, unsuccessful 
performance of these operations indicates that the device cannot perform an autoscan, so 
the autoscan error flag remains set in the registry. For instance, if the application 

20 program locks up due to an error during an attempted autoscan, the flag will not be 
cleared. During the next attempted use of the device, the system will recognize that the 
error flag is set, whereupon it will change the error bit in the registry to reflect that the 
device cannot perform autoscanning. As discussed above, this error bit informs the API 
module that the device cannot perform an autoscan, thereby disabling autoscanning and 

25 any associated dialog buttons during future operations with the device. 

After the autoscan error flag is set, the device is set to an automatic mode in a 
block 5 14 by the following code: 

// Set up for AutoScan 
// Set selected X resolution 
30 twCapability.Cap = ICAP_XRESOLUTION; 

twCapability.ConType = TWON_ONEVALUE; 
twCapability.hContainer = GlobalAIIoc (GHND, sizeof 
(TWJDNEVALUE)); 
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ptwOneValue = (pTW.ONEVALUE) GlobalLock 
(twCapability.hContainer) 
ptwOneValue->ltemType = TWTY_FIX32; 
ptwOneValue->ltem = XRes; 
5 TWAIN_Entry( DAT_CAPABILITY, MSG_SET, 

(TW_MEMREF)&twCapability, &m_SourcelD); 

// Set selected Y resolution 
twCapability.Cap = ICAP_YRESOLUTION; 
10 twCapability.ConType = TWON_ONEVALUE; 

twCapability.hContainer = GlobalAlloc (GHND, sizeof 
(TW_ONEVALUE)); 

ptwOneValue = (pTW_ONEVALUE) GlobalLock 
(twCapability.hContainer) 
15 ptwOneValue->ltemType = TWTY_FIX32; 

ptwOneValue->ltem = YRes; 
TWAIN_Entry( DAT_CAP ABILITY, MSG_SET, 

(TW_MEMREF)&twCapability, &m_SourcelD); 

20 // Find maximum scan size and set to do it. 

TWAIN_Entry( DATJMAGELAYOUT, MSG_GET, 
(TW_MEMREF)&twlmageLayout, &m_SourcelD, DGJMAGE); 
TWAIN_Entry( DATJMAGELAYOUT, MSG_SET, 
(TW_MEMREF)&twlmageLayout, &m_SourcelD, DGJMAGE); 

25 

// Set pixels to RGB 

twCapability.Cap = ICAP_ PIXELTYPE; 

twCapability.ConType = TWON_ONEVALUE; 

twCapability.hContainer = GlobalAlloc (GHND, sizeof 
30 (TWONEVALUE)); 

ptwOneValue = (pTW_ONEVALUE) GlobalLock 

(twCapability.hContainer) 

ptwOneValue->ltemType = TWTY_ UINT16; 

ptwOneValue->ltem = TWPT_RGB; 
35 TWAIN_Entry( DAT_CAPABILITY, MSG_SET, 

(TW_MEMREF)&twCapability, &m_SourcelD); 

Next, in a block 516, an edge detection algorithm is used to identify the external 
boundaries of the image. Typically, it is desired to acquire an image from a printed 
source image, such as a picture in a book. It is often the case that the picture in the 
40 book only occupies a portion of the maximum scanning area of the image acquisition 
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device. The raw data produced by most image acquisition devices is in the form of a 
bitmap, either grayscale or color. Each pixel in the bitmap corresponds to a pixel in the 
scanned image. As a result, the number of pixels in the bitmap will depend on the size 
of the scanned image, and the selected resolution of the device. By using edge 
5 detection, the size of the scanned image can be reduced to the size of the source image 
itself (i.e., limit to the extents of the picture), rather than the entire scanning area of the 
device. Edge detection algorithms are well known in the art, and the specific algorithm 
employed in the present invention need not be discussed herein. The edge detection 
algorithm will not work on images that do not have well-defined boundaries, such as a 

10 page of text with a picture inset into the text. 

Color and contrast/brightness correction are then performed using the bitmap 
data in a block 518. An algorithm based on well-known gamma table color correction 
techniques (not discussed here) is used to correct the color of the image. Color 
correction is not used if the device output data doesn't include color information. 

15 Additional well-known algorithms (not discussed here) are used to adjust the contrast 
and/or brightness of the captured image. 

At this point, the image data are almost ready to be inserted into an application 
program document. The steps to complete the image acquisition process are performed 
in a block 520, which first saves the corrected bitmap data to a bitmap file in a temporary 

20 buffer. The bitmap file is then processed by a JPEG compression algorithm that stores 
the image in a compressed JPEG File Interchange Format (JFIF) format in the buffer. 
JPEG compression greatly reduces the amount of data required to represent the image, 
while maintaining the quality of the original image. JPEG compression is well known in 
the art, and the algorithm for producing the JPEG output need not be discussed herein. 

25 After the image has been converted into a compressed JPEG format, it is ready to 

be inserted into the application document. After the image is inserted into the document, 
the autoscan error flag is cleared in the registry to indicate that the autoscan operations 
(blocks 514, 516,518,520) were successful. As discussed above, if the autoscan 
operations are not successful, then the autoscan flag will not be reset. As a result, during 

30 the next attempted use of the device, the system will recognize that the devices error flag 
has not been cleared, and will set the device's autoscan error bit in the registry to disable 
autoscanning with the device. 

In order to perform autoscanning, it is necessary to negotiate the capabilities of 
the image acquisition device prior to initiating the scanning process. Since it is desired 
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that the autoscan option require minimal user input, the capabilities of the image 
acquisition device are preferably negotiated based on predetermined criteria. These 
criteria include a predetermined resolution and a predetermined JPEG compression level. 
The predetermined resolution will be dependant on the type of document that is being 
5 created. For instance, a different (lower) resolution is preferably employed for 
documents that are to be displayed on web pages, and a higher resolution is used for 
images in documents that are to be viewed in printed form. 

The settings for the predetermined criteria and other parameters and flags are 
stored in the operating system registry. Rather than save these settings within each 
10 application (or each application document), the registry provides a central location for 
storing and retrieving this information. The following information is stored in the 
registry under the following key: 

"HKEY_CURRENT_USER\\Software\\Microsoft\\Office\9 



TABLE 4 



Name 


Value 


Description 


DEVICEXX - XX from 0 to 
number of devices on system 


TWAIN ID 


Value as returned by TWAIN 


FLAGSXX-XXfromOto 
number of devices on system 


FLAGS as defined below 


Data from the 

K)S_DEVICE_XXX and/or as 
determined by the software 


Device 


TWAIN ID 


Last device used 


Resolution 


High word -same as FLAGS 
Low word - 0 = Web, 
1= Print 


Hags for last device selected and 
last resolution selected 


JPEGLEVEL 


70 


Nominal JPEG compression level 


PRINTSCANRES 


150 


Nominal resolution for print scan 


WEBSCANRES 


96 


Nominal resolution for web scan 
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TABLE5 



FLAGS Description 



CAN_AUTOSCAN=l 


Enable "Insert" button 


CAN_CUSTOMSCAN = 2 


Enable "Custom" button 


CAN_WEB_RESOLUTION = 4 


Enable <e Web" button 


CAN j>RINTJRESOLUTION = 8 


Enable 'Trinf button 


TRY1NG_AUT0SCAN = 16 


This bit is set before a "one button scan" is attempted. If 
there is a failure, the next time the device is selected, this 
bit is iead and the 'Insert" button is disabled for that device 
from then on by turning off the CANAUTOSCAN flag. 
If the scan is successful, the flag is reset 


IS_A_CAMERA = 32 


Device is a camera 


B_A_FLATBED = 64 


Device is a flatbed scanner 


B_A_SHEETFED = 128 


Device is a sheetfed scanner 


IS_AN_OTHER = 256 


Device is an other 



Note that in a preferred embodiment, the predetermined resolution values are 

150 DPI (dots per inch) for a printed document, and 96 DPI for a web page 

5 document. The JPEG compression level is also set at a 70% quality level. 

In addition to the foregoing data, other data concerning various common 

image acquisition devices are stored as resources data in the MSOTW9.DLL. The 

format of this resource data are of the form: 

IDS_DEVICE_XXX TWAIN ID DESCRIPTION NOAUTO(opL) 

10 IDSJ3EVICE_XXX is the resource (image acquisition device) ID. 

TWAIN ID is the name that TWAIN will send to the MSOTW9.DLL API when 

it queries the system for devices. Examples include the CANON™ IX-4025 and 

LOGITECH™ PageScan Color. The TWAIN ID may or may not be the same as the 

produce name (i.e., HEWLETT PACKARD™ Hex Scanner), and several different 

15 devices may share one TWAIN ID. 

The DESCRIPTION contains one of the following: 
FLATBED - Flatbed scanner 
SHEETFED - Sheetfed scanner 
OTHERSCANNER - Other scanner 

20 The NOAUTO entry is optional, and indicates whether or not autoscanning is 

supported by a given device. 
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Structure of the MSOTW9.DLL file 

As discussed above, the TWAIN integration API is stored in a dynamic link 
library called MSOTW9.DLL. The MSOTW.DLL dynamic link library is composed 
of several component files and libraries, as shown in Table 6 below. 
5 TABLE 6 



Component 


Function 


stdafx.cpp 


Precompiled Header 


acquire.cpp 


Handles initialization and control of MSOTW9.dll and acquisition of 
image(s) from device 


calcbrit.cpp 


Contrast/Brightness adjustment 


edge.cpp 


Edge Detection 


Filldata.cpp 


Make .bmp file from TWAIN supplied image data 


fmmx.cpp 


Test for MMX capability 


imgstats.cpp 


Contrast/Brightness adjustment 


matrifce.cpp 


Contrast/Brightness adjustment 


ScanDlg.cpp 


MSOTW9.DLL User interface 


ScanMgr.cpp 


Top level interface to TWAIN wrapper class 


Setting.cpp 


Registry handler 


Wrap.cpp 


TWAIN wrapper class 


msotw9.cpp 


Main and utility functions 


msotw9.def 


Export symbols 


msotw9.rc 


Resources 


Jpeg.lib 


Static JPEG library built as part of OFFICE 2000™ 


Nmfcutls.lib 


Utility library 


Tw9jpeg.lib 


Interface to JPEG.lib 



The MSOTW9.DLL Entry 

The MSOTW9.DLL API provides a single entry point using an 
Acquirelmage( ) procedure call. The Acquirelmage( ) call has the following format: 

Acquirelmage ( IDispatch* ppAppl , 
10 bool skipDialog, 

OLECHAR* fileName, 
int length) 

The "Idispatch* ppAppl" parameter provides a pointer to the application that is 
calling the MSOTW9.DLL API. This parameter also identifies the application 
1 5 requesting API services, which is used when formatting the image data when the image is 
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inserted into an application program document (see below). The "skipDialog" parameter 
is a Boolean value (TRUE or FALSE) that identifies whether the API should use or 
bypass the built-in user interface for a selected image acquisition device. The 
"OLECHAR* fileName" parameter allows the application to specify a folder in which to 
5 save the image data. This step is optional - in most cases the image data are simply 
inserted into a document without saving the image to a file or files. The "length" 
parameter is presently not used, but may be available for future use. 

The Acquirelmage( ) procedure call returns a TRUE or FALSE Boolean 
value. A return value of TRUE indicates that the procedure was successfully 

10 executed. A return value of FALSE indicates that there was a problem in the 
execution of the procedure. 
Application Program Examples 

FIGURE 10 includes a flowchart describing the logical process that is used by an 
OFFICE 2000 application program, such as Microsoft Corporation's WORD 2000™, 

1 5 when inserting an image into a document using the MSOTW9.DLL API. In a block 600, 
a user installs the image acquisition device by attaching the device's communication 
cable to the user's computer via one of the computer's communication ports, such as a 
parallel, serial, USB port, Firewire port, or SCSI port, as appropriate. The user must also 
install the driver.ds device driver file for the device, or alternately, the driver.ds file may 

20 be included in a driver.dll library that is already installed on the computer (generally as 
part of the operating system). This step is performed in a block 602. The user may 
optionally install multiple image acquisition devices and drivers. 

Assuming that the device(s) and its driver(s) have been installed, the user launches 
the application program (e.g., the WORD 2000 word processing program) in a block 604, 

25 and initiates the image acquisition process by selecting <e Insert->Picture->AcquireImage" 
from the application program's Insert drop-down menu. This step activates a selection 
dialog 700 as shown in FIGURE 1 1 A. The selection dialog comprises a drop-down 
menu selection control 702, a "Web Quality" radio button 704, a "Print Quality" radio 
button 706, an "Insert" button 708, a "Custom Insert" button 710, and a "Cancel" 

30 button 712. The drop-down menu control comprises a control field 714, an menu 
activation button 716, and a drop-down menu 718 (see FIGURE 11B). The control field 
displays the image acquisition device that is presently selected for use. 

As shown in FIGURE 11B, activation of the menu activation button causes a 
drop-down menu to appear, providing a list of image acquisition devices that are 
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available for use. The list of available devices (and their autoscaiming capabilities) is 
generated by performing the process shown in the logic flowchart of FIGURE 7, as 
discussed above. The user then selects one of the devices in the list (such as a 
camera 2 device 720), as shown by a block 606. When a user selects the "Acquire 
5 Image" menu option for the first time within a given WORD 2000 session, the 
control field will contain the name of the first device found. If this is not the first 
request to acquire an image during a session, then the control field will display the 
device that was used during the most recent image acquisition (such as a scanner 2 
device 722), the identity of which is stored in the registry. 

10 If the selected device supports autoscanning, the "Web Quality" and "Print 

Quality" radio buttons will be enabled, allowing the user to select a scanning 
resolution that can be used for autoscanning, as indicated by a block 608. (The "Web 
Quality" and "Print Quality" radio buttons will be disabled if the selected device does 
not support autoscanning.) The default setting for these radio buttons will correspond 

15 to the resolution that was used during the most recent image acquisition, which is 
stored in the registry. These radio buttons represent a desired predefined image 
resolution. Selecting the "Web Quality" option causes a scanning device to autoscan 
an image at 96 DPI. Selecting the "Print Quality" option causes a scanning device to 
autoscan an image at 150 DPI 

20 At this point, the user may elect to automatically insert an image by activating 

the "Insert" button, or instead choose to insert an image using custom settings by 
activating the "Custom Insert" button. Optionally, the user may cancel the process by 
activating the "Cancel" button. 

If the user activates the "Insert" button, the process flows to a block 610, 

25 which initiates the automatic scanning sequence shown in FIGURE 9 at starting point 
B. An image is then automatically scanned with the selected image acquisition 
device and resolution, processed, and inserted into the active WORD 2000 document 
by using the autoscan process shown in FIGURE 9, as described above, without 
requiring any further input from the user. 

30 If the user desires to have more control over the image, or if the selected 

device does not support autoscanning (in which case the "Insert" button will be 
disabled), the user will select the "Custom Insert" button, corresponding to a 
block 612. The "Custom Insert" option allows a user to select customized image 
capture parameters for the image, such as pixel resolution (the radio button 
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corresponding to the print quality setting in dialog 700 will be disregarded). The 
logic then proceeds to a block 614, which launches the selected device's built-in 
(Source) user interface dialog. The user can then set various image capture 
parameters, such as resolution, color or black and white, data format, etc, as indicated 
5 by a block 616. The image is then captured and output to the application in a 
block 618 based on the image capture parameters settings. 

The insertion point of the captured image depends on the application that is 
being used. In WORD 2000, the image will be inserted so that its upper left-hand 
corner corresponds to the current cursor position when the process was initiated by 
10 the user. In EXCEL 2000™, the image will be inserted in the active cell of the active 
spreadsheet document. In POWERPOINT 2000™, the image will be inserted on the 
slide that is presently active. As discussed above, the MSOTW9.DLL API can 
determine which application program is using its services through the "Idispatch* 
ppAppl" parameter. 

15 In the case where the selected image acquisition device is a digital camera, a 

plurality of images may be selected to be inserted into an application program 
document by choosing a digital camera as the image acquisition device and selecting 
the "Custom Image" option. Note that not all digital cameras support this feature. In 
order to select a plurality of images for insertion, it is necessary that the selected 

20 device's built-in user interface provide a scheme for selecting a plurality of images 
that are stored in the device. Such a user interface will typically comprise one or 
more dialogs that enable a user to select the images he or she wishes to acquire. For 
instance, the device's user interface may provide a dialog comprising a selection area 
displaying multiple thumbnail images representing all of the images that are stored in 

25 the digital camera or image database. The user chooses one or more images to be 
inserted into an application program document by selecting the thumbnails 
corresponding to those images, and then activating an interface control to indicate 
that the selection process is complete. Steps similar to those discussed above for 
inserting a single image are then performed, including converting the image data into 

30 a JPEG format and performing color and/or contrast/brightness correction. Since 
many digital cameras provide images that already have color and/or 
contrast/brightness correction, it may not be necessary to perform any postprocessing 
on images output from these devices prior to inserting the images into a document. 
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The way the plurality of images will be inserted into the document depends on 
the application program that is being used. For example, in WORD 2000, the images 
are inserted in a sequentially tiled fashion, based on the default order the image data 
are output from the digital camera. (The MDOTW9.DLL module does not provide a 
5 means for controlling the order the images are output.) In EXCEL 2000, the images 
are inserted in a cascading fashion into the active cell of the active spreadsheet 
document. In POWERPOINT 2000, each of the captured images is inserted and 
preferably centered on a new separate slide. 
Exemplary Operating Environment 

10 FIGURE 12 and the following discussion are intended to provide a brief, general 

description of a suitable computing environment in which the invention may be 
implemented. The foregoing application programs (MICROSOFT WORD™, 
MICROSOFT EXCEL™, and MICROSOFT POWERPOINT™) and the dynamic link 
libraries (MSOTW9.DLL, TWAIN.DLL) and Source driver files (driver.ds files or .DLL 

15 file(s)) comprise a plurality of program modules that include routines, programs, objects, 
components, data structures, etc. that perform particular tasks or implement particular 
abstract data types. Moreover, those skilled in the art will appreciate that the invention 
may be practiced with other computer system configurations, including handheld 
devices, multiprocessor systems, microprocessor based or programmable consumer 

20 electronics, network PCs, minicomputers, mainframe computers, and the like. The 
invention may also be practiced in distributed computing environments where tasks are 
performed by remote processing devices that are linked through a communications 
network. In a distributed computing environment, program modules may be located in 
both local and remote memory storage devices. 

25 With reference to FIGURE 12, an exemplary system for implementing the 

invention includes a general purpose computing device in the form of a conventional 
personal computer 20, including a processing unit 21, a system memory 22, and a system 
bus 23 that couples various system components including the system memory to 
processing unit 21. System bus 23 may be any of several types of bus structures 

30 including a memory bus or memory controller, a peripheral bus, and a local bus using 
any of a variety of bus architectures. The system memory includes a read only memory 
(ROM) 24 and random access memory (RAM) 25. A basic input/output system 
(BIOS) 26, containing the basic routines that helps to transfer information between 
elements within personal computer 20, such as during start-up, is stored in ROM 24. 



MICR0154-l-l/0154ap doc 



-53- 



Personal computer 20 further includes a hard disk drive 27 for reading from and writing 
to a hard disk, not shown, a magnetic disk drive 28 for reading from or writing to a 
removable magnetic disk 29, and an optical disk drive 30 for reading from or writing to a 
removable optical disk 31 such as a CD-ROM or other optical media. Hard disk 
5 drive 27, magnetic disk drive 28, and optical disk drive 30 are connected to system 
bus 23 by a hard disk drive interface 32, a magnetic disk drive interface 33, and an 
optical disk drive interface 34, respectively. The drives and their associated computer 
readable media provide nonvolatile storage of computer readable instructions, data 
structures, program modules, and other data for personal computer 20. Although the 

10 exemplary environment described herein employs hard disk 27, a removable magnetic 
disk 29, and a removable optical disk 31, it should be appreciated by those skilled in the 
art that other types of computer readable media which can store data that is accessible by 
a computer, such as magnetic cassettes, flash memory cards, digital video disks, 
Bernoulli cartridges, RAMs, ROMs, and the like, may also be used in the exemplary 

1 5 operating environment. 

A number of program modules may be stored on hard disk 27, magnetic disk 29, 
optical disk 31, ROM 24, or RAM 25, including an operating system 35, one or more 
application programs 36, other program modules 37, and program data 38. A user may 
enter commands and information into personal computer 20 through input devices such 

20 as a keyboard 40 and a pointing device 42. Other input devices (not shown) may include 
a microphone, joystick, game pad, satellite dish, scanner, or the like. These and other 
input devices are often connected to processing unit 21 through a serial port interface 46 
that is coupled to the system bus, but may be connected by other interfaces, such as a 
parallel port, game port, or a universal serial bus (USB). A monitor 47 or other type of 

25 display device is also connected to system bus 23 via an interface, such as a video 
adapter 48. In addition to the monitor, personal computers typically include other 
peripheral output devices (not shown), such as speakers and printers. 

Personal computer 20 may operate in a networked environment using logical 
connections to one or more remote computers, such as a remote computer 49. Remote 

30 computer 49 may be another personal computer, a server, a router, a network PC, a 
peer device, or other common network node, and typically includes many or all of the 
elements described above relative to personal computer 20, although only a memory 
storage device 50 has been illustrated in FIGURE 12. The logical connections depicted 
in FIGURE 12 include a local area network (LAN) 51 and a wide area network 
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(WAN) 52. Such networking environments are commonplace in offices, enterprise 

wide computer networks, intranets, and the Internet. 

When used in a LAN networking environment, personal computer 20 is 

connected to local network 51 through a network interface or adapter 53. When used 
5 in a WAN networking environment, personal computer 20 typically includes a 

modem 54 or other means for establishing communications over WAN 52, such as 

the Internet. Modem 54, which may be internal or external, is connected to system 

bus 23 via serial port interface 46. In a networked environment, program modules 

depicted relative to personal computer 20, or portions thereof, may be stored in the 
10 remote memory storage device. It will be appreciated that the network connections 

shown are exemplary and other means of establishing a communications link between 

the computers may be used. 

Although the present invention has been described in connection with the 

preferred form of practicing it, those of ordinary skill in the art will understand that 
15 many modifications can be made thereto within the scope of the claims that follow. 

Accordingly, it is not intended that the scope of the invention in any way be limited 

by the above description, but instead be determined entirely by reference to the 

claims that follow. 
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The invention in which an exclusive right is claimed is defined by the following: 

1. A method for inserting an image into a document having a text content 
produced by an application program, the application program executing on a 
computer in communication with at least one image source device, the method 
comprising the steps of: 

(a) making an image source device active; 

(b) acquiring an image using the image source device that is 

active; and 

(c) inserting data representing said image into said document so 
that the image appears in the document and comprises a portion of the document, all 
without saving said data in other than a temporary buffer. 

2. The method of claim 1, further comprising the steps of: 

(a) creating a list of all image source devices in communication 
with the computer; and 

(b) enabling a user to select the image source device that is active 

from the list. 

3. The method of claim 1, wherein the active image source device 
comprises one of a scanner and a digital camera. 

4. The method of claim 1, wherein the step of acquiring the image 
comprises the step of scanning a graphic source that has defined edges, further 
comprising the steps of automatically detecting the edges of the graphic source, and 
cropping the image at the edges of the graphic source to exclude any portion of a 
scanned field beyond the edges of the graphic source from the image represented by 
the data inserted into the document. 

5. The method of claim 1, further comprising the step of converting the data 
representing the image into a compressed format prior to inserting the data into the 
document. 

6. The method of claim 1 , further including the steps of: 

(a) selecting at least one image enhancement criterion; and 

(b) enhancing said captured image based on said image 
enhancement criterion prior to inserting said data representing the image into said 
document. 
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7. The method of claim 6, wherein the image enhancement criterion is a 
contrast level of the image that is adjusted to enhance a brightness of the image 
within the document. 

8. The method of claim 6, wherein the image enhancement criterion is a 
color level of the image that is adjusted to enhance a color relationship of the image 
inserted within the document, based on a gamma correction algorithm. 

9. The method of claim 1, further comprising the step of the application 
program negotiating with the image source device that is active to determine a set of 
image capture parameters that control said image source device when acquiring the 
image. 

10. The method of claim 9, further comprising the step of determining a 
set of capabilities of the image source device that is active, wherein the set of image 
capture parameters are negotiated based in part on the capabilities of said image 
source device. 

11. The method of claim 10, wherein a set of capabilities are associated 
with the image source devices connected with the computer and are stored in an 
operating system registry. 

12. The method of claim 1, further comprising the step of determining 
whether the image source device that is active is able to perform an automatic image 
scan, wherein the automatic image scan comprises the steps of capturing an image of 
a graphic source with said image source device and inserting the data representing the 
image into the document, all without requiring a user to select image capture 
parameters. 

13. The method of claim 12, wherein the image source device that is 
active has an X resolution and a Y resolution and includes a driver that provides a 
user interface for selecting image capture parameters, the step of determining if said 
image source device can perform the automatic image scan comprises the steps of: 

(a) confirming that said image source device can control its X 

resolution; 
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(b) confirming that said image source device can control its Y 

resolution; and 

(c) confirming that the user interface of said image source device 
can be bypassed, wherein an affirmative answer to all of the steps of confirming 
indicates that said image source device can perform the automatic image scan. 

14. The method of claim 12, wherein the step of determining if said image 
source device can perform the automatic image scan comprises the steps of: 

(a) setting an error flag; 

(b) attempting to perform an automatic image scan; 

(c) clearing the error flag if the automatic image scan is 
successful; and 

(d) evaluating the error flag during a subsequent use of the image 
source device, whereby if the error flag has not been cleared, the image source device 
cannot perform an automatic image scan. 

15. The method of claim 12, wherein if it is determined that said image 
source device can perform an automatic image scan, enabling a user of the 
application program to selectively cause the image to be acquired and the data 
representing the image to be inserted into the document, all with a single user control 
selection. 

16. A computer-readable medium having computer-executable 
instructions for performing the steps recited in claim 1. 

17. A computer-readable medium having computer-executable 
instructions for performing the steps recited in claim 12. 

18. A method for inserting a plurality of images into a document having a 
text content that is produced with an application program, the application program 
running on a computer in communication with an image source device that stores 
image source data comprising multiple images, the method comprising the steps of: 

(a) enabling an image source device user interface that provides a 
selection scheme for selecting a plurality of the stored multiple images for insertion 
into the document; 
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(b) enabling a user to select a plurality of images to be inserted 
into the document; 

(c) transferring data representing the selected images from the 
image source device to the computer; 

(d) converting said data representing the selected image into a 
compressed format; and 

(e) inserting said compressed format image data into the document 
so that the document includes the plurality of images. 

19. The method of claim 18, wherein the application program is a word 
processing application, and the plurality of images are inserted into the document as a 
plurality of tiled images. 

20. The method of claim 18, wherein the application program is a 
spreadsheet application that produces a spreadsheet document, and the plurality of 
inserted images are inserted into the spreadsheet document as a plurality of cascaded 
images. 

21. The method of claim 18, wherein the application program is a 
presentation design application, and the plurality of inserted images are inserted into a 
presentation document as a plurality of individual slides. 

22. The method of claim 18, further including the step of performing a 
postprocessing modification to said data to enhance a quality of the plurality of 
images. 

23. A computer-readable medium having computer-executable 
instructions for performing the steps recited in claim 18. 

24. A system for inserting an image into a document produced by an 
application program, the system comprising: 

(a) a computer having a memory and a processor, the memory 
storing machine instructions that are executable on the processor; 

(b) an application program comprising machine instructions that 
are stored in the computer memory; 
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(c) an image acquisition device connected in communication with 
the computer and providing image data representing an image; 

(d) a source driver module comprising computer-executable 
instructions stored in the memory and in communication with the image acquisition 
device so as to control acquisition of an image from the image acquisition device; 

(e) a source manager module comprising computer-executable 
instructions stored in the memory and in communication with the source driver 
module, the source manager module providing commands to the source driver 
module to acquire an image from the image acquisition device; and 

(f) an interface module comprising computer-executable 
instructions stored in the memory and in communication with the source manager 
module and the application program, the interface module providing commands to the 
source manager to acquire an image from the image acquisition device, the data 
representing the image being inserted into the application program document. 

25. The system of claim 24, wherein the application program is a word 
processing application. 

26. The system of claim 24, wherein the application program is a 
spreadsheet application. 

27. The system of claim 24, wherein the application program is a 
presentation design application. 

28. The system of claim 24, wherein the source manager module complies 
with the TWAIN communication specification. 

29. The system of claim 24, wherein the application program is able to 
request the interface module to acquire an image by issuing a single procedure call to 
the interface module. 

30. The system of claim 24, wherein the application program provides a 
user interface that enables a user to acquire an image from the image acquisition 
device and insert the data representing the image into the application program 
document by selecting a single application menu option and performing a single 
subsequent user action. 
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31. The system of claim 24, wherein the interface module comprises 
additional computer-executable instructions for enhancing the quality of the captured 
image, the captured image quality being enhanced prior to inserting the data 
representing the image into the application program document. 

32. The system of claim 24, wherein the image is acquired by scanning a 
graphic source that has edges, and the interface module comprises additional 
computer-executable instructions for detecting the edges of the graphic source so as 
to automatically crop a scanned field to include only the portion of the scanned field 
included within the graphic source in the image, the image being so cropped prior to 
the data representing the image being inserted into the document. 

33. The system of claim 24, wherein the interface module comprises 
additional computer-executable instructions for converting the data representing the 
image into a compressed format, said data being converted into the compressed 
format prior to being inserted into the document. 
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SYSTEM AND METHODS FOR ACQUIRING IMAGES FROM IMAGING 

DEVICES 
Abstract of the Disclosure 

A system and associated method for acquiring images from various imaging 
devices and inserting these acquired images into application program documents. 
The system includes an interface module, a source manager module, and a source 
module, the latter two supporting the TWAIN communication specification. The 
interface module allows word processing applications, spreadsheet applications, 
presentation design applications, and other types of applications to be provided the 
capability for easily inserting images into documents that are created by such 
applications. An application program interface (API) is provided with an program 
application that enables the application program to acquire images from any TWAIN 
compliant image acquisition device. The method defines a process for automatically 
capturing and inserting an image with minimal user input, and enables a user to 
customize image capture parameters when acquiring an image, if desired. The 
interface module also provides several image enhancement functions, including color 
correction, brightness/contrast correction, automatic cropping, and image 
compression, which are again implemented with minimal user interaction, thereby 
greatly simplifying the task of inserting an image into a document. There is no need 
to scan an image and save it in a file that persists after the application program is no 
longer running. Instead, the image is inserted directly into the document, in a 
compressed format. However, for image application devices that do not support 
autoscanning in this manner, or if the user prefers more control, the API enables the 
user interface for the selected image acquisition source to be executed. 
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